Ember.Set Class packages/ember-runtime/lib/system/set.js:14
Extends: Ember.CoreObject
Uses: Ember.MutableEnumerable
Uses: Ember.Copyable
Uses: Ember.Freezable
Defined in: packages/ember-runtime/lib/system/set.js:14
Module: ember-runtime
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()
.
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(); |
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.
Methods
- _scheduledDestroy
- add
- addEach
- addEnumerableObserver
- addObject
- addObjects
- any
- anyBy
- clear
- compact
- contains
- copy
- create
- createWithMixins
- destroy
- eachComputedProperty
- enumerableContentDidChange
- enumerableContentWillChange
- every
- everyBy
- everyProperty
- extend
- filter
- filterBy
- filterProperty
- find
- findBy
- findProperty
- forEach
- freeze
- frozenCopy
- getEach
- init
- invoke
- isEqual
- map
- mapBy
- mapProperty
- metaForProperty
- nextObject
- pop
- push
- reduce
- reject
- rejectBy
- rejectProperty
- remove
- removeEach
- removeEnumerableObserver
- removeObject
- removeObjects
- reopen
- reopenClass
- setEach
- shift
- some
- someProperty
- sortBy
- toArray
- toString
- uniq
- unshift
- willDestroy
- without
Properties
_scheduledDestroy
private
add
(obj)
Ember.Set
Adds an object to the set. Only non-null
objects can be added to a set
and those can only be added once. If the object is already in the set or
the passed value is null this method will have no effect.
This is an alias for Ember.MutableEnumerable.addObject()
.
1 2 3 4 5 6 |
var colors = new Ember.Set(); colors.add("blue"); // ["blue"] colors.add("blue"); // ["blue"] colors.add("red"); // ["blue", "red"] colors.add(null); // ["blue", "red"] colors.add(undefined); // ["blue", "red"] |
Parameters:
- obj Object
- The object to add.
Returns:
- Ember.Set
- The set itself.
addEach
(objects)
Ember.Set
Adds each object in the passed enumerable to the set.
This is an alias of Ember.MutableEnumerable.addObjects()
1 2 |
var colors = new Ember.Set(); colors.addEach(["red", "green", "blue"]); // ["red", "green", "blue"] |
Parameters:
- objects Ember.Enumerable
- the objects to add.
Returns:
- Ember.Set
- The set itself.
addEnumerableObserver
(target, opts)
Registers an enumerable observer. Must implement Ember.EnumerableObserver
mixin.
Parameters:
- target Object
- opts Hash
Returns:
- this
addObject
(object)
Object
Required. You must implement this method to apply this mixin.
Attempts to add the passed object to the receiver if the object is not already present in the collection. If the object is present, this method has no effect.
If the passed object is of a type not supported by the receiver, then this method should raise an exception.
Parameters:
- object Object
- The object to add to the enumerable.
Returns:
- Object
- the passed object
addObjects
(objects)
Object
Adds each object in the passed enumerable to the receiver.
Parameters:
- objects Ember.Enumerable
- the objects to add.
Returns:
- Object
- receiver
any
(callback, target)
Boolean
Returns true
if the passed function returns true for any item in the
enumeration. This corresponds with the some()
method in JavaScript 1.6.
The callback method you provide should have the following signature (all parameters are optional):
1 |
function(item, index, enumerable);
|
item
is the current item in the iteration.index
is the current index in the iteration.enumerable
is the enumerable object itself.
It should return the true
to include the item in the results, false
otherwise.
Note that in addition to a callback, you can also pass an optional target
object that will be set as this
on the context. This is a good way
to give your iterator function access to the current object.
Usage Example:
1 |
if (people.any(isManager)) { Paychecks.addBiggerBonus(); }
|
Parameters:
- callback Function
- The callback to execute
- target Object
- The target object to use
Returns:
- Boolean
- `true` if the passed function returns `true` for any item
anyBy
(key, value)
Boolean
Returns true
if the passed property resolves to true
for any item in
the enumerable. This method is often simpler/faster than using a callback.
Returns:
- Boolean
- `true` if the passed function returns `true` for any item
clear
Ember.Set
Clears the set. This is useful if you want to reuse an existing set without having to recreate it.
1 2 3 4 |
var colors = new Ember.Set(["red", "green", "blue"]); colors.length; // 3 colors.clear(); colors.length; // 0 |
Returns:
- Ember.Set
- An empty Set
compact
Array
Returns a copy of the array with all null and undefined elements removed.
1 2 |
var arr = ["a", null, "c", undefined]; arr.compact(); // ["a", "c"] |
Returns:
- Array
- the array without null and undefined elements.
contains
(obj)
Boolean
Returns true
if the passed object can be found in the receiver. The
default version will iterate through the enumerable until the object
is found. You may want to override this with a more efficient version.
1 2 3 |
var arr = ["a", "b", "c"]; arr.contains("a"); // true arr.contains("z"); // false |
Parameters:
- obj Object
- The object to search for.
Returns:
- Boolean
- `true` if object is found in enumerable.
copy
(deep)
Object
Override to return a copy of the receiver. Default implementation raises an exception.
Parameters:
- deep Boolean
- if `true`, a deep copy of the object should be made
Returns:
- Object
- copy of receiver
create
(arguments)
static
Creates an instance of a class. Accepts either no arguments, or an object containing values to initialize the newly instantiated object with.
1 2 3 4 5 6 7 8 9 10 11 |
App.Person = Ember.Object.extend({ helloWorld: function() { alert("Hi, my name is " + this.get('name')); } }); var tom = App.Person.create({ name: 'Tom Dale' }); tom.helloWorld(); // alerts "Hi, my name is Tom Dale". |
create
will call the init
function if defined during
Ember.AnyObject.extend
If no arguments are passed to create
, it will not set values to the new
instance during initialization:
1 2 |
var noName = App.Person.create(); noName.helloWorld(); // alerts undefined |
NOTE: For performance reasons, you cannot declare methods or computed
properties during create
. You should instead declare methods and computed
properties when using extend
or use the createWithMixins
shorthand.
Parameters:
- arguments
createWithMixins
(arguments)
static
Equivalent to doing extend(arguments).create()
.
If possible use the normal create
method instead.
Parameters:
- arguments
destroy
Ember.Object
Destroys an object by setting the isDestroyed
flag and removing its
metadata, which effectively destroys observers and bindings.
If you try to set a property on a destroyed object, an exception will be raised.
Note that destruction is scheduled for the end of the run loop and does not happen immediately. It will set an isDestroying flag immediately.
Returns:
- Ember.Object
- receiver
eachComputedProperty
(callback, binding)
Iterate over each computed property for the class, passing its name
and any associated metadata (see metaForProperty
) to the callback.
Parameters:
- callback Function
- binding Object
enumerableContentDidChange
(start, removing, adding)
Invoke this method when the contents of your enumerable has changed. This will notify any observers watching for content changes. If your are implementing an ordered enumerable (such as an array), also pass the start and end values where the content changed so that it can be used to notify range observers.
Parameters:
- start Number
- optional start offset for the content change. For unordered enumerables, you should always pass -1.
- removing Ember.Enumerable|Number
- An enumerable of the objects to be removed or the number of items to be removed.
- adding Ember.Enumerable|Number
- An enumerable of the objects to be added or the number of items to be added.
enumerableContentWillChange
(removing, adding)
Invoke this method just before the contents of your enumerable will change. You can either omit the parameters completely or pass the objects to be removed or added if available or just a count.
Parameters:
- removing Ember.Enumerable|Number
- An enumerable of the objects to be removed or the number of items to be removed.
- adding Ember.Enumerable|Number
- An enumerable of the objects to be added or the number of items to be added.
every
(callback, target)
Boolean
Returns true
if the passed function returns true for every item in the
enumeration. This corresponds with the every()
method in JavaScript 1.6.
The callback method you provide should have the following signature (all parameters are optional):
1 |
function(item, index, enumerable);
|
item
is the current item in the iteration.index
is the current index in the iteration.enumerable
is the enumerable object itself.
It should return the true
or false
.
Note that in addition to a callback, you can also pass an optional target
object that will be set as this
on the context. This is a good way
to give your iterator function access to the current object.
Example Usage:
1 |
if (people.every(isEngineer)) { Paychecks.addBigBonus(); }
|
Parameters:
- callback Function
- The callback to execute
- target Object
- The target object to use
Returns:
- Boolean
everyBy
(key, value)
Boolean
Returns true
if the passed property resolves to true
for all items in
the enumerable. This method is often simpler/faster than using a callback.
Returns:
- Boolean
everyProperty
(key, value)
Boolean
deprecated
Returns true
if the passed property resolves to true
for all items in
the enumerable. This method is often simpler/faster than using a callback.
Returns:
- Boolean
extend
(mixins, arguments)
static
Creates a new subclass.
1 2 3 4 5 |
App.Person = Ember.Object.extend({ say: function(thing) { alert(thing); } }); |
This defines a new subclass of Ember.Object: App.Person
. It contains one method: say()
.
You can also create a subclass from any existing class by calling its extend()
method. For example, you might want to create a subclass of Ember's built-in Ember.View
class:
1 2 3 4 |
App.PersonView = Ember.View.extend({ tagName: 'li', classNameBindings: ['isAdministrator'] }); |
When defining a subclass, you can override methods but still access the implementation of your parent class by calling the special _super()
method:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 |
App.Person = Ember.Object.extend({ say: function(thing) { var name = this.get('name'); alert(name + ' says: ' + thing); } }); App.Soldier = App.Person.extend({ say: function(thing) { this._super(thing + ", sir!"); }, march: function(numberOfHours) { alert(this.get('name') + ' marches for ' + numberOfHours + ' hours.') } }); var yehuda = App.Soldier.create({ name: "Yehuda Katz" }); yehuda.say("Yes"); // alerts "Yehuda Katz says: Yes, sir!" |
The create()
on line #17 creates an instance of the App.Soldier
class. The extend()
on line #8 creates a subclass of App.Person
. Any instance of the App.Person
class will not have the march()
method.
You can also pass Ember.Mixin
classes to add additional properties to the subclass.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
App.Person = Ember.Object.extend({ say: function(thing) { alert(this.get('name') + ' says: ' + thing); } }); App.SingingMixin = Ember.Mixin.create({ sing: function(thing){ alert(this.get('name') + ' sings: la la la ' + thing); } }); App.BroadwayStar = App.Person.extend(App.SingingMixin, { dance: function() { alert(this.get('name') + ' dances: tap tap tap tap '); } }); |
The App.BroadwayStar
class contains three methods: say()
, sing()
, and dance()
.
Parameters:
- mixins Ember.Mixin
- One or more Ember.Mixin classes
- arguments Object
- Object containing values to use within the new class
filter
(callback, target)
Array
Returns an array with all of the items in the enumeration that the passed
function returns true for. This method corresponds to filter()
defined in
JavaScript 1.6.
The callback method you provide should have the following signature (all parameters are optional):
1 |
function(item, index, enumerable);
|
item
is the current item in the iteration.index
is the current index in the iteration.enumerable
is the enumerable object itself.
It should return the true
to include the item in the results, false
otherwise.
Note that in addition to a callback, you can also pass an optional target
object that will be set as this
on the context. This is a good way
to give your iterator function access to the current object.
Parameters:
- callback Function
- The callback to execute
- target Object
- The target object to use
Returns:
- Array
- A filtered array.
filterBy
(key, value)
Array
Returns an array with just the items with the matched property. You
can pass an optional second argument with the target value. Otherwise
this will match any property that evaluates to true
.
Returns:
- Array
- filtered array
filterProperty
(key, value)
Array
deprecated
Returns an array with just the items with the matched property. You
can pass an optional second argument with the target value. Otherwise
this will match any property that evaluates to true
.
Returns:
- Array
- filtered array
find
(callback, target)
Object
Returns the first item in the array for which the callback returns true.
This method works similar to the filter()
method defined in JavaScript 1.6
except that it will stop working on the array once a match is found.
The callback method you provide should have the following signature (all parameters are optional):
1 |
function(item, index, enumerable);
|
item
is the current item in the iteration.index
is the current index in the iteration.enumerable
is the enumerable object itself.
It should return the true
to include the item in the results, false
otherwise.
Note that in addition to a callback, you can also pass an optional target
object that will be set as this
on the context. This is a good way
to give your iterator function access to the current object.
Parameters:
- callback Function
- The callback to execute
- target Object
- The target object to use
Returns:
- Object
- Found item or `undefined`.
findBy
(key, value)
Object
Returns the first item with a property matching the passed value. You
can pass an optional second argument with the target value. Otherwise
this will match any property that evaluates to true
.
This method works much like the more generic find()
method.
Returns:
- Object
- found item or `undefined`
findProperty
(key, value)
Object
deprecated
Returns the first item with a property matching the passed value. You
can pass an optional second argument with the target value. Otherwise
this will match any property that evaluates to true
.
This method works much like the more generic find()
method.
Returns:
- Object
- found item or `undefined`
forEach
(callback, target)
Object
Iterates through the enumerable, calling the passed function on each
item. This method corresponds to the forEach()
method defined in
JavaScript 1.6.
The callback method you provide should have the following signature (all parameters are optional):
1 |
function(item, index, enumerable);
|
item
is the current item in the iteration.index
is the current index in the iteration.enumerable
is the enumerable object itself.
Note that in addition to a callback, you can also pass an optional target
object that will be set as this
on the context. This is a good way
to give your iterator function access to the current object.
Parameters:
- callback Function
- The callback to execute
- target Object
- The target object to use
Returns:
- Object
- receiver
freeze
Object
Freezes the object. Once this method has been called the object should no longer allow any properties to be edited.
Returns:
- Object
- receiver
frozenCopy
Object
If the object implements Ember.Freezable
, then this will return a new
copy if the object is not frozen and the receiver if the object is frozen.
Raises an exception if you try to call this method on a object that does not support freezing.
You should use this method whenever you want a copy of a freezable object since a freezable object can simply return itself without actually consuming more memory.
Returns:
- Object
- copy of receiver or receiver
getEach
(key)
Array
Alias for mapBy
Parameters:
- key String
- name of the property
Returns:
- Array
- The mapped array.
init
An overridable method called when objects are instantiated. By default, does nothing unless it is overridden during class definition.
Example:
1 2 3 4 5 6 7 8 9 10 11 |
App.Person = Ember.Object.extend({ init: function() { alert('Name is ' + this.get('name')); } }); var steve = App.Person.create({ name: "Steve" }); // alerts 'Name is Steve'. |
NOTE: If you do override init
for a framework class like Ember.View
or
Ember.ArrayController
, be sure to call this._super()
in your
init
declaration! If you don't, Ember may not have an opportunity to
do important setup work, and you'll see strange behavior in your
application.
invoke
(methodName, args)
Array
Invokes the named method on every object in the receiver that implements it. This method corresponds to the implementation in Prototype 1.6.
Parameters:
- methodName String
- the name of the method
- args Object...
- optional arguments to pass as well.
Returns:
- Array
- return values from calling invoke.
isEqual
(obj)
Boolean
Returns true if the passed object is also an enumerable that contains the same objects as the receiver.
1 2 3 4 5 |
var colors = ["red", "green", "blue"], same_colors = new Ember.Set(colors); same_colors.isEqual(colors); // true same_colors.isEqual(["purple", "brown"]); // false |
Parameters:
- obj Ember.Set
- the other object.
Returns:
- Boolean
map
(callback, target)
Array
Maps all of the items in the enumeration to another value, returning
a new array. This method corresponds to map()
defined in JavaScript 1.6.
The callback method you provide should have the following signature (all parameters are optional):
1 |
function(item, index, enumerable);
|
item
is the current item in the iteration.index
is the current index in the iteration.enumerable
is the enumerable object itself.
It should return the mapped value.
Note that in addition to a callback, you can also pass an optional target
object that will be set as this
on the context. This is a good way
to give your iterator function access to the current object.
Parameters:
- callback Function
- The callback to execute
- target Object
- The target object to use
Returns:
- Array
- The mapped array.
mapBy
(key)
Array
Similar to map, this specialized function returns the value of the named property on all items in the enumeration.
Parameters:
- key String
- name of the property
Returns:
- Array
- The mapped array.
mapProperty
(key)
Array
deprecated
Similar to map, this specialized function returns the value of the named property on all items in the enumeration.
Parameters:
- key String
- name of the property
Returns:
- Array
- The mapped array.
metaForProperty
(key)
In some cases, you may want to annotate computed properties with additional metadata about how they function or what values they operate on. For example, computed property functions may close over variables that are then no longer available for introspection.
You can pass a hash of these values to a computed property like this:
1 2 3 4 |
person: function() { var personId = this.get('personId'); return App.Person.create({ id: personId }); }.property().meta({ type: App.Person }) |
Once you've done this, you can retrieve the values saved to the computed property from your class like this:
1 |
MyClass.metaForProperty('person');
|
This will return the original hash that was passed to meta()
.
Parameters:
- key String
- property name
nextObject
(index, previousObject, context)
Object
Implement this method to make your class enumerable.
This method will be call repeatedly during enumeration. The index value will always begin with 0 and increment monotonically. You don't have to rely on the index value to determine what object to return, but you should always check the value and start from the beginning when you see the requested index is 0.
The previousObject
is the object that was returned from the last call
to nextObject
for the current iteration. This is a useful way to
manage iteration if you are tracing a linked list, for example.
Finally the context parameter will always contain a hash you can use as a "scratchpad" to maintain any other state you need in order to iterate properly. The context object is reused and is not reset between iterations so make sure you setup the context with a fresh state whenever the index parameter is 0.
Generally iterators will continue to call nextObject
until the index
reaches the your current length-1. If you run out of data before this
time for some reason, you should simply return undefined.
The default implementation of this method simply looks up the index. This works great on any Array-like objects.
Parameters:
- index Number
- the current index of the iteration
- previousObject Object
- the value returned by the last call to `nextObject`.
- context Object
- a context object you can use to maintain state.
Returns:
- Object
- the next object in the iteration or undefined
pop
Object
Removes the last element from the set and returns it, or null
if it's empty.
1 2 3 4 |
var colors = new Ember.Set(["green", "blue"]); colors.pop(); // "blue" colors.pop(); // "green" colors.pop(); // null |
Returns:
- Object
- The removed object from the set or null.
push
Ember.Set
Inserts the given object on to the end of the set. It returns the set itself.
This is an alias for Ember.MutableEnumerable.addObject()
.
1 2 3 4 |
var colors = new Ember.Set(); colors.push("red"); // ["red"] colors.push("green"); // ["red", "green"] colors.push("blue"); // ["red", "green", "blue"] |
Returns:
- Ember.Set
- The set itself.
reduce
(callback, initialValue, reducerProperty)
Object
This will combine the values of the enumerator into a single value. It
is a useful way to collect a summary value from an enumeration. This
corresponds to the reduce()
method defined in JavaScript 1.8.
The callback method you provide should have the following signature (all parameters are optional):
1 |
function(previousValue, item, index, enumerable);
|
previousValue
is the value returned by the last call to the iterator.item
is the current item in the iteration.index
is the current index in the iteration.enumerable
is the enumerable object itself.
Return the new cumulative value.
In addition to the callback you can also pass an initialValue
. An error
will be raised if you do not pass an initial value and the enumerator is
empty.
Note that unlike the other methods, this method does not allow you to pass a target object to set as this for the callback. It's part of the spec. Sorry.
Parameters:
Returns:
- Object
- The reduced value.
reject
(callback, target)
Array
Returns an array with all of the items in the enumeration where the passed function returns false for. This method is the inverse of filter().
The callback method you provide should have the following signature (all parameters are optional):
1 |
function(item, index, enumerable); |
- item is the current item in the iteration.
- index is the current index in the iteration
- enumerable is the enumerable object itself.
It should return the a falsey value to include the item in the results.
Note that in addition to a callback, you can also pass an optional target object that will be set as "this" on the context. This is a good way to give your iterator function access to the current object.
Parameters:
- callback Function
- The callback to execute
- target Object
- The target object to use
Returns:
- Array
- A rejected array.
rejectBy
(key, value)
Array
Returns an array with the items that do not have truthy values for key. You can pass an optional second argument with the target value. Otherwise this will match any property that evaluates to false.
Returns:
- Array
- rejected array
rejectProperty
(key, value)
Array
deprecated
Returns an array with the items that do not have truthy values for key. You can pass an optional second argument with the target value. Otherwise this will match any property that evaluates to false.
Returns:
- Array
- rejected array
remove
(obj)
Ember.Set
Removes the object from the set if it is found. If you pass a null
value
or an object that is already not in the set, this method will have no
effect. This is an alias for Ember.MutableEnumerable.removeObject()
.
1 2 3 4 |
var colors = new Ember.Set(["red", "green", "blue"]); colors.remove("red"); // ["blue", "green"] colors.remove("purple"); // ["blue", "green"] colors.remove(null); // ["blue", "green"] |
Parameters:
- obj Object
- The object to remove
Returns:
- Ember.Set
- The set itself.
removeEach
(objects)
Ember.Set
Removes each object in the passed enumerable to the set.
This is an alias of Ember.MutableEnumerable.removeObjects()
1 2 |
var colors = new Ember.Set(["red", "green", "blue"]); colors.removeEach(["red", "blue"]); // ["green"] |
Parameters:
- objects Ember.Enumerable
- the objects to remove.
Returns:
- Ember.Set
- The set itself.
removeEnumerableObserver
(target, opts)
Removes a registered enumerable observer.
Parameters:
- target Object
- opts Hash
Returns:
- this
removeObject
(object)
Object
Required. You must implement this method to apply this mixin.
Attempts to remove the passed object from the receiver collection if the object is present in the collection. If the object is not present, this method has no effect.
If the passed object is of a type not supported by the receiver, then this method should raise an exception.
Parameters:
- object Object
- The object to remove from the enumerable.
Returns:
- Object
- the passed object
removeObjects
(objects)
Object
Removes each object in the passed enumerable from the receiver.
Parameters:
- objects Ember.Enumerable
- the objects to remove
Returns:
- Object
- receiver
reopen
Augments a constructor's prototype with additional
properties and functions:
javascript
MyObject = Ember.Object.extend({
name: 'an object'
});
o = MyObject.create();
o.get('name'); // 'an object'
MyObject.reopen({
say: function(msg){
console.log(msg);
}
})
o2 = MyObject.create();
o2.say("hello"); // logs "hello"
o.say("goodbye"); // logs "goodbye"
To add functions and properties to the constructor itself,
see reopenClass
reopenClass
Augments a constructor's own properties and functions:
1 2 3 4 5 6 7 8 9 10 11 |
MyObject = Ember.Object.extend({ name: 'an object' }); MyObject.reopenClass({ canBuild: false }); MyObject.canBuild; // false o = MyObject.create(); |
In other words, this creates static properties and functions for the class. These are only available on the class and not on any instance of that class.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 |
App.Person = Ember.Object.extend({ name : "", sayHello : function(){ alert("Hello. My name is " + this.get('name')); } }); App.Person.reopenClass({ species : "Homo sapiens", createPerson: function(newPersonsName){ return App.Person.create({ name:newPersonsName }); } }); var tom = App.Person.create({ name : "Tom Dale" }); var yehuda = App.Person.createPerson("Yehuda Katz"); tom.sayHello(); // "Hello. My name is Tom Dale" yehuda.sayHello(); // "Hello. My name is Yehuda Katz" alert(App.Person.species); // "Homo sapiens" |
Note that species
and createPerson
are not valid on the tom
and yehuda
variables. They are only valid on App.Person
.
To add functions and properties to instances of
a constructor by extending the constructor's prototype
see reopen
setEach
(key, value)
Object
Sets the value on the named property for each member. This is more
efficient than using other methods defined on this helper. If the object
implements Ember.Observable, the value will be changed to set(),
otherwise
it will be set directly. null
objects are skipped.
Parameters:
- key String
- The key to set
- value Object
- The object to set
Returns:
- Object
- receiver
shift
Object
Removes the last element from the set and returns it, or null
if it's empty.
This is an alias for Ember.Set.pop()
.
1 2 3 4 |
var colors = new Ember.Set(["green", "blue"]); colors.shift(); // "blue" colors.shift(); // "green" colors.shift(); // null |
Returns:
- Object
- The removed object from the set or null.
some
(callback, target)
Boolean
deprecated
Returns true
if the passed function returns true for any item in the
enumeration. This corresponds with the some()
method in JavaScript 1.6.
The callback method you provide should have the following signature (all parameters are optional):
1 |
function(item, index, enumerable);
|
item
is the current item in the iteration.index
is the current index in the iteration.enumerable
is the enumerable object itself.
It should return the true
to include the item in the results, false
otherwise.
Note that in addition to a callback, you can also pass an optional target
object that will be set as this
on the context. This is a good way
to give your iterator function access to the current object.
Usage Example:
1 |
if (people.some(isManager)) { Paychecks.addBiggerBonus(); }
|
Parameters:
- callback Function
- The callback to execute
- target Object
- The target object to use
Returns:
- Boolean
- `true` if the passed function returns `true` for any item
someProperty
(key, value)
Boolean
deprecated
Returns true
if the passed property resolves to true
for any item in
the enumerable. This method is often simpler/faster than using a callback.
Returns:
- Boolean
- `true` if the passed function returns `true` for any item
sortBy
(property)
Array
Converts the enumerable into an array and sorts by the keys specified in the argument.
You may provide multiple arguments to sort by multiple properties.
Parameters:
- property String
- name(s) to sort on
Returns:
- Array
- The sorted array.
toArray
Array
Simply converts the enumerable into a genuine array. The order is not guaranteed. Corresponds to the method implemented by Prototype.
Returns:
- Array
- the enumerable as an array.
toString
String
Returns a string representation which attempts to provide more information
than Javascript's toString
typically does, in a generic way for all Ember
objects.
1 2 3 |
App.Person = Em.Object.extend() person = App.Person.create() person.toString() //=> "<App.Person:ember1024>" |
If the object's class is not defined on an Ember namespace, it will indicate it is a subclass of the registered superclass:
1 2 3 |
Student = App.Person.extend() student = Student.create() student.toString() //=> "<(subclass of App.Person):ember1025>" |
If the method toStringExtension
is defined, its return value will be
included in the output.
1 2 3 4 5 6 7 |
App.Teacher = App.Person.extend({ toStringExtension: function() { return this.get('fullName'); } }); teacher = App.Teacher.create() teacher.toString(); //=> "<App.Teacher:ember1026:Tom Dale>" |
Returns:
- String
- string representation
uniq
Ember.Enumerable
Returns a new enumerable that contains only unique values. The default implementation returns an array regardless of the receiver type.
1 2 |
var arr = ["a", "a", "b", "b"]; arr.uniq(); // ["a", "b"] |
Returns:
unshift
Ember.Set
Inserts the given object on to the end of the set. It returns the set itself.
This is an alias of Ember.Set.push()
1 2 3 4 |
var colors = new Ember.Set(); colors.unshift("red"); // ["red"] colors.unshift("green"); // ["red", "green"] colors.unshift("blue"); // ["red", "green", "blue"] |
Returns:
- Ember.Set
- The set itself.
willDestroy
Override to implement teardown.
without
(value)
Ember.Enumerable
Returns a new enumerable that excludes the passed value. The default implementation returns an array regardless of the receiver type unless the receiver does not contain the value.
1 2 |
var arr = ["a", "b", "a", "c"]; arr.without("a"); // ["b", "c"] |
Parameters:
- value Object
Returns:
[]
Ember.Array
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.
Returns:
- this
concatenatedProperties
Array
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:
1 2 3 4 5 6 7 8 9 10 11 12 13 |
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:
1 2 3 4 5 6 |
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:
1 2 3 4 |
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. Since it changes expectations about behavior of properties, you should properly document its usage in each individual concatenated property (to not mislead your users to think they can override the property in a subclass).
Default: null
firstObject
Object
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
.
1 2 3 4 5 |
var arr = ["a", "b", "c"]; arr.get('firstObject'); // "a" var arr = []; arr.get('firstObject'); // undefined |
Returns:
- Object
- the object or undefined
hasEnumerableObservers
Boolean
Becomes true whenever the array currently has observers watching changes on the array.
isDestroyed
Destroyed object property flag.
if this property is true
the observers and bindings were already
removed by the effect of calling the destroy()
method.
Default: false
isDestroying
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.
Default: false
isFrozen
Boolean
Set to true
when the object is frozen. Use this property to detect
whether your object is frozen or not.
lastObject
Object
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
.
1 2 3 4 5 |
var arr = ["a", "b", "c"]; arr.get('lastObject'); // "c" var arr = []; arr.get('lastObject'); // undefined |
Returns:
- Object
- the last object or undefined
length
number
// .......................................................... // IMPLEMENT ENUMERABLE APIS // /** This property will change as the number of objects in the set changes.
Default: 0