Ember.Array Class
This mixin implements Observer-friendly Array-like behavior. It is not a concrete implementation, but it can be used up by other classes that want to appear like arrays.
For example, ArrayProxy and ArrayController are both concrete classes that can be instantiated to implement array-like behavior. Both of these classes use the Array Mixin by way of the MutableArray mixin, which allows observable changes to be made to the underlying array.
Unlike Ember.Enumerable, this mixin defines methods specifically for
collections that provide index-ordered access to their contents. When you
are designing code that needs to accept any kind of Array-like object, you
should use these methods instead of Array primitives because these will
properly notify observers of changes to the array.
Although these methods are efficient, they do add a layer of indirection to your application so it is a good idea to use them only when you need the flexibility of using both true JavaScript arrays and "virtual" arrays such as controllers and collections.
You can use the methods defined in this module to access and modify array
contents in a KVO-friendly way. You can also be notified whenever the
membership of an array changes by using .observes('myArray.[]').
To support Ember.Array in your own class, you must override two
primitives to use it: replace() and objectAt().
Note that the Ember.Array mixin also incorporates the Ember.Enumerable
mixin. All Ember.Array-like objects are also enumerable.
Item Index
Methods
- addArrayObserver
- addEnumerableObserver
- any
- anyBy deprecated
- arrayContentDidChange
- arrayContentWillChange
- compact
- contains
- enumerableContentDidChange
- enumerableContentWillChange
- every
- everyBy deprecated
- everyProperty deprecated
- filter
- filterBy
- filterProperty deprecated
- find
- findBy
- findProperty deprecated
- forEach
- getEach
- indexOf
- invoke
- isAny
- isEvery
- lastIndexOf
- map
- mapBy
- mapProperty deprecated
- nextObject
- objectAt
- objectsAt
- reduce
- reject
- rejectBy
- rejectProperty deprecated
- removeArrayObserver
- removeEnumerableObserver
- setEach
- slice
- some deprecated
- someProperty deprecated
- sortBy
- toArray
- uniq
- without
Methods
addArrayObserver
-
target -
opts
Adds an array observer to the receiving array. The array observer object normally must implement two methods:
arrayWillChange(observedObj, start, removeCount, addCount)- This method will be called just before the array is modified.arrayDidChange(observedObj, start, removeCount, addCount)- This method will be called just after the array is modified.
Both callbacks will be passed the observed object, starting index of the change as well a a count of the items to be removed and added. You can use these callbacks to optionally inspect the array during the change, clear caches, or do any other bookkeeping necessary.
In addition to passing a target, you can also include an options hash which you can use to override the method names that will be invoked on the target.
Parameters:
-
targetObjectThe observer object.
-
optsHashOptional hash of configuration options including
willChangeanddidChangeoption.
Returns:
receiver
addEnumerableObserver
-
target -
[opts]
Ember.EnumerableObserver
mixin.
Parameters:
-
targetObject -
[opts]Hash optional
Returns:
any
-
callback -
[target]
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):
`javascript
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:
`javascript
if (people.any(isManager)) { Paychecks.addBiggerBonus(); }
`
Parameters:
-
callbackFunctionThe callback to execute -
[target]Object optionalThe target object to use
Returns:
true if the passed function returns true for any item
anyBy
-
key -
[value]
Returns:
true if the passed function returns true for any item
arrayContentDidChange
-
startIdx -
removeAmt -
addAmt
If you are implementing an object that supports Ember.Array, call this
method just after the array content changes to notify any observers and
invalidate any related properties. Pass the starting index of the change
as well as a delta of the amounts to change.
Parameters:
-
startIdxNumberThe starting index in the array that did change.
-
removeAmtNumberThe number of items that were removed. If you pass
nullassumes 0 -
addAmtNumberThe number of items that were added. If you pass
nullassumes 0.
Returns:
receiver
arrayContentWillChange
-
startIdx -
removeAmt -
addAmt
If you are implementing an object that supports Ember.Array, call this
method just before the array content changes to notify any observers and
invalidate any related properties. Pass the starting index of the change
as well as a delta of the amounts to change.
Parameters:
-
startIdxNumberThe starting index in the array that will change.
-
removeAmtNumberThe number of items that will be removed. If you pass
nullassumes 0 -
addAmtNumberThe number of items that will be added. If you pass
nullassumes 0.
Returns:
receiver
compact
()
Array
`javascript
var arr = ["a", null, "c", undefined];
arr.compact(); // ["a", "c"]
`
Returns:
contains
-
obj
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.
`javascript
var arr = ["a", "b", "c"];
arr.contains("a"); // true
arr.contains("z"); // false
`
Parameters:
-
objObjectThe object to search for.
Returns:
true if object is found in enumerable.
enumerableContentDidChange
-
removing -
adding
Parameters:
-
removingEmber.Enumerable | NumberAn enumerable of the objects to be removed or the number of items to be removed. -
addingEmber.Enumerable | NumberAn enumerable of the objects to be added or the number of items to be added.
enumerableContentWillChange
-
removing -
adding
Parameters:
-
removingEmber.Enumerable | NumberAn enumerable of the objects to be removed or the number of items to be removed. -
addingEmber.Enumerable | NumberAn enumerable of the objects to be added or the number of items to be added.
every
-
callback -
[target]
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):
`javascript
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:
`javascript
if (people.every(isEngineer)) { Paychecks.addBigBonus(); }
`
Parameters:
-
callbackFunctionThe callback to execute -
[target]Object optionalThe target object to use
Returns:
everyBy
-
key -
[value]
Returns:
everyProperty
-
key -
[value]
Returns:
filter
-
callback -
[target]
filter() defined in
JavaScript 1.6.
The callback method you provide should have the following signature (all
parameters are optional):
`javascript
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:
-
callbackFunctionThe callback to execute -
[target]Object optionalThe target object to use
Returns:
filterBy
-
key -
[value]
true.
Parameters:
-
keyStringthe property to test -
[value]optionaloptional value to test against.
Returns:
filterProperty
-
key -
[value]
true.
Returns:
find
-
callback -
[target]
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):
`javascript
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:
-
callbackFunctionThe callback to execute -
[target]Object optionalThe target object to use
Returns:
undefined.
findBy
-
key -
[value]
true.
This method works much like the more generic find() method.
Returns:
undefined
findProperty
-
key -
[value]
true.
This method works much like the more generic find() method.
Returns:
undefined
forEach
-
callback -
[target]
forEach() method defined in
JavaScript 1.6.
The callback method you provide should have the following signature (all
parameters are optional):
`javascript
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:
-
callbackFunctionThe callback to execute -
[target]Object optionalThe target object to use
Returns:
getEach
-
key
mapBy
Parameters:
-
keyStringname of the property
Returns:
indexOf
-
object -
startAt
Returns the index of the given object's first occurrence.
If no startAt argument is given, the starting location to
search is 0. If it's negative, will count backward from
the end of the array. Returns -1 if no match is found.
var arr = ["a", "b", "c", "d", "a"];
arr.indexOf("a"); // 0
arr.indexOf("z"); // -1
arr.indexOf("a", 2); // 4
arr.indexOf("a", -1); // 4
arr.indexOf("b", 3); // -1
arr.indexOf("a", 100); // -1
Parameters:
-
objectObjectthe item to search for
-
startAtNumberoptional starting location to search, default 0
Returns:
index or -1 if not found
invoke
-
methodName -
args
Parameters:
-
methodNameStringthe name of the method -
argsObject...optional arguments to pass as well.
Returns:
isAny
-
key -
[value]
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:
true if the passed function returns true for any item
isEvery
-
key -
[value]
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:
lastIndexOf
-
object -
startAt
Returns the index of the given object's last occurrence.
If no startAt argument is given, the search starts from
the last position. If it's negative, will count backward
from the end of the array. Returns -1 if no match is found.
var arr = ["a", "b", "c", "d", "a"];
arr.lastIndexOf("a"); // 4
arr.lastIndexOf("z"); // -1
arr.lastIndexOf("a", 2); // 0
arr.lastIndexOf("a", -1); // 4
arr.lastIndexOf("b", 3); // 1
arr.lastIndexOf("a", 100); // 4
Parameters:
-
objectObjectthe item to search for
-
startAtNumberoptional starting location to search, default 0
Returns:
index or -1 if not found
map
-
callback -
[target]
map() defined in JavaScript 1.6.
The callback method you provide should have the following signature (all
parameters are optional):
`javascript
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:
-
callbackFunctionThe callback to execute -
[target]Object optionalThe target object to use
Returns:
mapBy
-
key
Parameters:
-
keyStringname of the property
Returns:
mapProperty
-
key
Parameters:
-
keyStringname of the property
Returns:
nextObject
-
index -
previousObject -
context
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:
-
indexNumberthe current index of the iteration -
previousObjectObjectthe value returned by the last call tonextObject. -
contextObjecta context object you can use to maintain state.
Returns:
objectAt
-
idx
Returns the object at the given index. If the given index is negative
or is greater or equal than the array length, returns undefined.
This is one of the primitives you must implement to support Ember.Array.
If your object supports retrieving the value of an array item using get()
(i.e. myArray.get(0)), then you do not need to implement this method
yourself.
var arr = ['a', 'b', 'c', 'd'];
arr.objectAt(0); // "a"
arr.objectAt(3); // "d"
arr.objectAt(-1); // undefined
arr.objectAt(4); // undefined
arr.objectAt(5); // undefined
Parameters:
-
idxNumberThe index of the item to return.
Returns:
item at index or undefined
objectsAt
-
indexes
This returns the objects at the specified indexes, using objectAt.
var arr = ['a', 'b', 'c', 'd'];
arr.objectsAt([0, 1, 2]); // ["a", "b", "c"]
arr.objectsAt([2, 3, 4]); // ["c", "d", undefined]
Parameters:
-
indexesArrayAn array of indexes of items to return.
Returns:
reduce
-
callback -
initialValue -
reducerProperty
reduce() method defined in JavaScript 1.8.
The callback method you provide should have the following signature (all
parameters are optional):
`javascript
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:
reject
-
callback -
[target]
`javascript
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:
-
callbackFunctionThe callback to execute -
[target]Object optionalThe target object to use
Returns:
rejectBy
-
key -
[value]
Returns:
rejectProperty
-
key -
[value]
Returns:
removeArrayObserver
-
target -
opts
Removes an array observer from the object if the observer is current registered. Calling this method multiple times with the same object will have no effect.
Parameters:
-
targetObjectThe object observing the array.
-
optsHashOptional hash of configuration options including
willChangeanddidChangeoption.
Returns:
receiver
removeEnumerableObserver
-
target -
[opts]
Parameters:
-
targetObject -
[opts]Hash optional
Returns:
setEach
-
key -
value
set(), otherwise
it will be set directly. null objects are skipped.
Parameters:
-
keyStringThe key to set -
valueObjectThe object to set
Returns:
slice
-
beginIndex -
endIndex
Returns a new array that is a slice of the receiver. This implementation uses the observable array methods to retrieve the objects for the new slice.
var arr = ['red', 'green', 'blue'];
arr.slice(0); // ['red', 'green', 'blue']
arr.slice(0, 2); // ['red', 'green']
arr.slice(1, 100); // ['green', 'blue']
Parameters:
-
beginIndexInteger(Optional) index to begin slicing from.
-
endIndexInteger(Optional) index to end the slice at (but not included).
Returns:
New array with specified slice
some
-
callback -
[target]
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):
`javascript
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:
`javascript
if (people.some(isManager)) { Paychecks.addBiggerBonus(); }
`
Parameters:
-
callbackFunctionThe callback to execute -
[target]Object optionalThe target object to use
Returns:
true if the passed function returns true for any item
someProperty
-
key -
[value]
Returns:
true if the passed function returns true for any item
sortBy
-
property
Parameters:
-
propertyStringname(s) to sort on
Returns:
toArray
()
Array
Returns:
uniq
()
Ember.Enumerable
`javascript
var arr = ["a", "a", "b", "b"];
arr.uniq(); // ["a", "b"]
`
Returns:
without
-
value
`javascript
var arr = ["a", "b", "a", "c"];
arr.without("a"); // ["b", "c"]
`
Parameters:
-
valueObject
Returns:
Properties
@each
Unknown
Returns a special object that can be used to observe individual properties on the array. Just get an equivalent property on this object and it will return an enumerable that maps automatically to the named key on the member objects.
If you merely want to watch for any items being added or removed to the array,
use the [] property instead of @each.
[]
Unknown
This is the handler for the special array content property. If you get this property, it will return this. If you set this property it a new array, it will replace the current content.
This property overrides the default property defined in Ember.Enumerable.
firstObject
Unknown
undefined.
`javascript
var arr = ["a", "b", "c"];
arr.get('firstObject'); // "a"
var arr = [];
arr.get('firstObject'); // undefined
`
hasArrayObservers
Boolean
Becomes true whenever the array currently has observers watching changes on the array.
hasEnumerableObservers
Boolean
lastObject
Unknown
undefined.
`javascript
var arr = ["a", "b", "c"];
arr.get('lastObject'); // "c"
var arr = [];
arr.get('lastObject'); // undefined
`
length
Number
Your array must support the length property. Your replace methods should
set this property whenever it changes.