API Docs for: v2.11.0-beta.8
Show:

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.

Methods

addArrayObserver

(
  • target
  • opts
)
Ember.Array public

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 Object

    The observer object.

  • opts Object

    Optional hash of configuration options including willChange and didChange option.

Returns:

Ember.Array:

receiver

addObject

(
  • obj
)
Ember.Array public

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:

Ember.Array:

receiver

addObjects

(
  • objects
)
Object public
Adds each object in the passed enumerable to the receiver.

Parameters:

Returns:

Object: receiver

arrayContentDidChange

(
  • startIdx
  • removeAmt
  • addAmt
)
Ember.Array public

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 Number

    The starting index in the array that did change.

  • removeAmt Number

    The number of items that were removed. If you pass null assumes 0

  • addAmt Number

    The number of items that were added. If you pass null assumes 0.

Returns:

Ember.Array:

receiver

arrayContentWillChange

(
  • startIdx
  • removeAmt
  • addAmt
)
Ember.Array public

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 Number

    The starting index in the array that will change.

  • removeAmt Number

    The number of items that will be removed. If you pass null assumes 0

  • addAmt Number

    The number of items that will be added. If you pass null assumes 0.

Returns:

Ember.Array:

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:

Ember.Array:

An empty Array.

includes

(
  • obj
  • startAt
)
Boolean public

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 Object

    The object to search for.

  • startAt Number

    optional starting location to search, default 0

Returns:

Boolean:

true if object is found in the array.

indexOf

(
  • object
  • startAt
)
Number public

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 Object

    the item to search for

  • startAt Number

    optional starting location to search, default 0

Returns:

Number:

index or -1 if not found

insertAt

(
  • idx
  • object
)
Ember.Array public

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 Number

    index of insert the object at.

  • object Object

    object to insert

Returns:

Ember.Array:

receiver

lastIndexOf

(
  • object
  • startAt
)
Number public

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 Object

    the item to search for

  • startAt Number

    optional starting location to search, default 0

Returns:

Number:

index or -1 if not found

objectAt

(
  • idx
)
public

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 Number

    The index of the item to return.

Returns:

:

item at index or undefined

objectsAt

(
  • indexes
)
Array public

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 Array

    An array of indexes of items to return.

Returns:

Array:

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
)
public

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
)
Ember.Array public

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:

Returns:

Ember.Array:

receiver

removeArrayObserver

(
  • target
  • opts
)
Ember.Array public

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 Object

    The object observing the array.

  • opts Object

    Optional hash of configuration options including willChange and didChange option.

Returns:

Ember.Array:

receiver

removeAt

(
  • start
  • len
)
Ember.Array public

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 Number

    index, start of range

  • len Number

    length of passing range

Returns:

Ember.Array:

receiver

removeObject

(
  • obj
)
Ember.Array public

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:

Ember.Array:

receiver

removeObjects

(
  • objects
)
Object public
Removes each object in the passed enumerable from the receiver.

Parameters:

Returns:

Object: receiver

replace

(
  • idx
  • amt
  • objects
)
public

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 Number

    Starting index in the array to replace. If idx >= length, then append to the end of the array.

  • amt Number

    Number of elements that should be removed from the array, starting at idx.

  • objects Array

    An 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:

Ember.Array:

receiver

setObjects

(
  • objects
)
Ember.Array public

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.Array

    array whose content will be used for replacing the content of the receiver

Returns:

Ember.Array:

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
)
Array public

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:

Array:

New array with specified slice

unshiftObject

(
  • obj
)
public

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
)
Ember.Array public

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:

Returns:

Ember.Array:

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.