Class Ember.Set

Uses: Ember.Freezable , Ember.Copyable , Ember.MutableEnumerable

Defined in: packages/ember-runtime/lib/system/set.js:14

Module: ember

Since: vEmber 0.9

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 Ember.Set#copy().

        
              // 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();

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.

Unlike arrays, 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: 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 Ember.Set#contains().

Observing changes

When using 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.

Other Methods

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.Enumerable and Ember.MutableEnumerable which implement most of the common iterator methods you are used to on Array.

Note that you can also use the Ember.Copyable and Ember.Freezable APIs on 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.

Show: Inherited Protected Private Deprecated

[]

Module: ember

Inherited from Ember.Enumerable packages/ember-runtime/lib/mixins/enumerable.js:818

returns: this

This property will trigger anytime the enumerable's content changes. You can observe this property to be notified of changes to the enumerables content.

For plain enumerables, this property is read only. Ember.Array overrides this method.

concatenatedProperties

Module: ember

Inherited from Ember.CoreObject packages/ember-runtime/lib/system/core_object.js:202

Defines the properties that will be concatenated from the superclass (instead of overridden).

By default, when you extend an Ember class a property defined in the subclass overrides a property with the same name that is defined in the superclass. However, there are some cases where it is preferable to build up a property's value by combining the superclass' property value with the subclass' value. An example of this in use within Ember is the classNames property of Ember.View.

Here is some sample code showing the difference between a concatenated property and a normal one:

        
              App.BarView = Ember.View.extend({
  someNonConcatenatedProperty: ['bar'],
  classNames: ['bar']
});

App.FooBarView = App.BarView.extend({
  someNonConcatenatedProperty: ['foo'],
  classNames: ['foo'],
});

var fooBarView = App.FooBarView.create();
fooBarView.get('someNonConcatenatedProperty'); // ['foo']
fooBarView.get('classNames'); // ['ember-view', 'bar', 'foo']

This behavior extends to object creation as well. Continuing the above example:

        
              var view = App.FooBarView.create({
  someNonConcatenatedProperty: ['baz'],
  classNames: ['baz']
})
view.get('someNonConcatenatedProperty'); // ['baz']
view.get('classNames'); // ['ember-view', 'bar', 'foo', 'baz']

Adding a single property that is not an array will just add it in the array:

        
              var view = App.FooBarView.create({
  classNames: 'baz'
})
view.get('classNames'); // ['ember-view', 'bar', 'foo', 'baz']

Using the concatenatedProperties property, we can tell to Ember that mix the content of the properties.

In Ember.View the classNameBindings and attributeBindings properties are also concatenated, in addition to classNames.

This feature is available for you to use throughout the Ember object model, although typical app developers are likely to use it infrequently.

firstObject Object

Module: ember

Inherited from Ember.Enumerable packages/ember-runtime/lib/mixins/enumerable.js:109

returns: Object; the object or undefined

Helper method returns the first object from a collection. This is usually used by bindings and other parts of the framework to extract a single object if the enumerable contains only one item.

If you override this method, you should implement it so that it will always return the same value each time it is called. If your enumerable contains only one object, this method should always return that object. If your enumerable is empty, this method should return undefined.

        
              var arr = ["a", "b", "c"];
arr.get('firstObject');  // "a"

var arr = [];
arr.get('firstObject');  // undefined

hasEnumerableObservers

Module: ember

Inherited from Ember.Enumerable packages/ember-runtime/lib/mixins/enumerable.js:879

Becomes true whenever the array currently has observers watching changes on the array.

isDestroyed

Module: ember

Inherited from Ember.CoreObject packages/ember-runtime/lib/system/core_object.js:267

Destroyed object property flag.

if this property is true the observers and bindings were already removed by the effect of calling the destroy() method.

isDestroying

Module: ember

Inherited from Ember.CoreObject packages/ember-runtime/lib/system/core_object.js:278

Destruction scheduled flag. The destroy() method has been called.

The object stays intact until the end of the run loop at which point the isDestroyed flag is set.

isFrozen

Module: ember

Inherited from Ember.Freezable packages/ember-runtime/lib/mixins/freezable.js:67

Set to true when the object is frozen. Use this property to detect whether your object is frozen or not.

lastObject Object

Module: ember

Inherited from Ember.Enumerable packages/ember-runtime/lib/mixins/enumerable.js:140

returns: Object; the last object or undefined

Helper method returns the last object from a collection. If your enumerable contains only one object, this method should always return that object. If your enumerable is empty, this method should return undefined.

        
              var arr = ["a", "b", "c"];
arr.get('lastObject');  // "c"

var arr = [];
arr.get('lastObject');  // undefined

length

Module: ember

Defined in packages/ember-runtime/lib/system/set.js:112

// .......................................................... // IMPLEMENT ENUMERABLE APIS // /** This property will change as the number of objects in the set changes.