Ember.MutableArray Class
This mixin defines the API for modifying array-like objects. These methods can be applied only to a collection that keeps its items in an ordered set. It builds upon the Array mixin and adds methods to modify the array. One concrete implementations of this class include ArrayProxy.
It is important to use the methods in this class to modify arrays so that changes are observable. This allows the binding system in Ember to function correctly.
Note that an Array can change even if it does not implement this mixin. For example, one might implement a SparseArray that cannot be directly modified, but if its underlying enumerable changes, it will change also.
Item Index
Methods
- addArrayObserver
- addObject
- addObjects
- arrayContentDidChange
- arrayContentWillChange
- clear
- includes
- indexOf
- insertAt
- lastIndexOf
- objectAt
- objectsAt
- popObject
- pushObject
- pushObjects
- removeArrayObserver
- removeAt
- removeObject
- removeObjects
- replace
- reverseObjects
- setObjects
- shiftObject
- slice
- unshiftObject
- unshiftObjects
Properties
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 as 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:
-
target
ObjectThe observer object.
-
opts
ObjectOptional hash of configuration options including
willChange
anddidChange
option.
Returns:
receiver
addObject
-
obj
Push the object onto the end of the array if it is not already present in the array.
let cities = ['Chicago', 'Berlin'];
cities.addObject('Lima'); // ['Chicago', 'Berlin', 'Lima']
cities.addObject('Berlin'); // ['Chicago', 'Berlin', 'Lima']
Parameters:
-
obj
object to add, if not already present
Returns:
receiver
addObjects
-
objects
Parameters:
-
objects
Ember.Enumerablethe objects to add.
Returns:
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:
-
startIdx
NumberThe starting index in the array that did change.
-
removeAmt
NumberThe number of items that were removed. If you pass
null
assumes 0 -
addAmt
NumberThe number of items that were added. If you pass
null
assumes 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:
-
startIdx
NumberThe starting index in the array that will change.
-
removeAmt
NumberThe number of items that will be removed. If you pass
null
assumes 0 -
addAmt
NumberThe number of items that will be added. If you pass
null
assumes 0.
Returns:
receiver
clear
()
Ember.Array
public
Remove all elements from the array. This is useful if you want to reuse an existing array without having to recreate it.
let colors = ['red', 'green', 'blue'];
colors.length; // 3
colors.clear(); // []
colors.length; // 0
Returns:
An empty Array.
includes
-
obj
-
startAt
Returns true
if the passed object can be found in the array.
This method is a Polyfill for ES 2016 Array.includes.
If no startAt
argument is given, the starting location to
search is 0. If it's negative, searches from the index of
this.length + startAt
by asc.
[1, 2, 3].includes(2); // true
[1, 2, 3].includes(4); // false
[1, 2, 3].includes(3, 2); // true
[1, 2, 3].includes(3, 3); // false
[1, 2, 3].includes(3, -1); // true
[1, 2, 3].includes(1, -1); // false
[1, 2, 3].includes(1, -4); // true
[1, 2, NaN].includes(NaN); // true
Parameters:
-
obj
ObjectThe object to search for.
-
startAt
Numberoptional starting location to search, default 0
Returns:
true
if object is found in the array.
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.
let 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:
-
object
Objectthe item to search for
-
startAt
Numberoptional starting location to search, default 0
Returns:
index or -1 if not found
insertAt
-
idx
-
object
This will use the primitive replace()
method to insert an object at the
specified index.
let colors = ['red', 'green', 'blue'];
colors.insertAt(2, 'yellow'); // ['red', 'green', 'yellow', 'blue']
colors.insertAt(5, 'orange'); // Error: Index out of range
Parameters:
-
idx
Numberindex of insert the object at.
-
object
Objectobject to insert
Returns:
receiver
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.
let 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:
-
object
Objectthe item to search for
-
startAt
Numberoptional starting location to search, default 0
Returns:
index or -1 if not found
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.
let 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:
-
idx
NumberThe index of the item to return.
Returns:
item at index or undefined
objectsAt
-
indexes
This returns the objects at the specified indexes, using objectAt
.
let arr = ['a', 'b', 'c', 'd'];
arr.objectsAt([0, 1, 2]); // ['a', 'b', 'c']
arr.objectsAt([2, 3, 4]); // ['c', 'd', undefined]
Parameters:
-
indexes
ArrayAn array of indexes of items to return.
Returns:
popObject
()
public
Pop object from array or nil if none are left. Works just like pop()
but
it is KVO-compliant.
let colors = ['red', 'green', 'blue'];
colors.popObject(); // 'blue'
console.log(colors); // ['red', 'green']
Returns:
object
pushObject
-
obj
Push the object onto the end of the array. Works just like push()
but it
is KVO-compliant.
let colors = ['red', 'green'];
colors.pushObject('black'); // ['red', 'green', 'black']
colors.pushObject(['yellow']); // ['red', 'green', ['yellow']]
Parameters:
-
obj
object to push
Returns:
object same object passed as a param
pushObjects
-
objects
Add the objects in the passed numerable to the end of the array. Defers notifying observers of the change until all objects are added.
let colors = ['red'];
colors.pushObjects(['yellow', 'orange']); // ['red', 'yellow', 'orange']
Parameters:
-
objects
Ember.Enumerablethe objects to add
Returns:
receiver
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:
-
target
ObjectThe object observing the array.
-
opts
ObjectOptional hash of configuration options including
willChange
anddidChange
option.
Returns:
receiver
removeAt
-
start
-
len
Remove an object at the specified index using the replace()
primitive
method. You can pass either a single index, or a start and a length.
If you pass a start and length that is beyond the
length this method will throw an OUT_OF_RANGE_EXCEPTION
.
let colors = ['red', 'green', 'blue', 'yellow', 'orange'];
colors.removeAt(0); // ['green', 'blue', 'yellow', 'orange']
colors.removeAt(2, 2); // ['green', 'blue']
colors.removeAt(4, 2); // Error: Index out of range
Parameters:
-
start
Numberindex, start of range
-
len
Numberlength of passing range
Returns:
receiver
removeObject
-
obj
Remove all occurrences of an object in the array.
let cities = ['Chicago', 'Berlin', 'Lima', 'Chicago'];
cities.removeObject('Chicago'); // ['Berlin', 'Lima']
cities.removeObject('Lima'); // ['Berlin']
cities.removeObject('Tokyo') // ['Berlin']
Parameters:
-
obj
object to remove
Returns:
receiver
removeObjects
-
objects
Parameters:
-
objects
Ember.Enumerablethe objects to remove
Returns:
replace
-
idx
-
amt
-
objects
Required. You must implement this method to apply this mixin.
This is one of the primitives you must implement to support Ember.Array
.
You should replace amt objects started at idx with the objects in the
passed array. You should also call this.enumerableContentDidChange()
Parameters:
-
idx
NumberStarting index in the array to replace. If idx >= length, then append to the end of the array.
-
amt
NumberNumber of elements that should be removed from the array, starting at idx.
-
objects
ArrayAn array of zero or more objects that should be inserted into the array at idx
reverseObjects
()
Ember.Array
public
Reverse objects in the array. Works just like reverse()
but it is
KVO-compliant.
Returns:
receiver
setObjects
-
objects
Replace all the receiver's content with content of the argument. If argument is an empty array receiver will be cleared.
let colors = ['red', 'green', 'blue'];
colors.setObjects(['black', 'white']); // ['black', 'white']
colors.setObjects([]); // []
Parameters:
-
objects
Ember.Arrayarray whose content will be used for replacing the content of the receiver
Returns:
receiver with the new content
shiftObject
()
public
Shift an object from start of array or nil if none are left. Works just
like shift()
but it is KVO-compliant.
let colors = ['red', 'green', 'blue'];
colors.shiftObject(); // 'red'
console.log(colors); // ['green', 'blue']
Returns:
object
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.
let arr = ['red', 'green', 'blue'];
arr.slice(0); // ['red', 'green', 'blue']
arr.slice(0, 2); // ['red', 'green']
arr.slice(1, 100); // ['green', 'blue']
Parameters:
-
beginIndex
Number(Optional) index to begin slicing from.
-
endIndex
Number(Optional) index to end the slice at (but not included).
Returns:
New array with specified slice
unshiftObject
-
obj
Unshift an object to start of array. Works just like unshift()
but it is
KVO-compliant.
let colors = ['red'];
colors.unshiftObject('yellow'); // ['yellow', 'red']
colors.unshiftObject(['black']); // [['black'], 'yellow', 'red']
Parameters:
-
obj
object to unshift
Returns:
object same object passed as a param
unshiftObjects
-
objects
Adds the named objects to the beginning of the array. Defers notifying observers until all objects have been added.
let colors = ['red'];
colors.unshiftObjects(['black', 'white']); // ['black', 'white', 'red']
colors.unshiftObjects('yellow'); // Type Error: 'undefined' is not a function
Parameters:
-
objects
Ember.Enumerablethe objects to add
Returns:
receiver
Properties
@each
Unknown
public
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.
@each
should only be used in a non-terminal context. Example:
myMethod: computed('posts.@each.author', function(){
...
});
If you merely want to watch for the array being changed, like an object being
replaced, added or removed, use []
instead of @each
.
myMethod: computed('posts.[]', function(){
...
});
[]
Unknown
public
This is the handler for the special array content property. If you get this property, it will return this. If you set this property to a new array, it will replace the current content.
This property overrides the default property defined in Ember.Enumerable
.
hasArrayObservers
Boolean
public
Becomes true whenever the array currently has observers watching changes on the array.
length
Number
public
Required. You must implement this method to apply this mixin.
Your array must support the length
property. Your replace methods should
set this property whenever it changes.