#

API Docs for: v2.11.1
Show: Inherited Protected Private Deprecated

# Ember.MutableArray Class

Uses

- Ember.Array
- Ember.MutableEnumerable

Defined in: `packages/ember-runtime/lib/mixins/mutable_array.js:41`
Module: ember-runtime
Parent Module: ember

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.

- Index
- Methods
- Properties

## 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

- @each
- []
- hasArrayObservers
- length

## Methods

### `addArrayObserver`

(

- `target`
- `opts`

)
Ember.Array public

Inherited from Ember.Array: `packages/ember-runtime/lib/mixins/array.js:454`

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

Inherited from Ember.MutableEnumerable but overwritten in `packages/ember-runtime/lib/mixins/mutable_array.js:374`

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

Inherited from Ember.MutableEnumerable: `packages/ember-runtime/lib/mixins/mutable_enumerable.js:72`

Adds each object in the passed enumerable to the receiver.

#### Parameters:

- `objects` Ember.Enumerable
  the objects to add.

#### Returns:

Object: receiver

### `arrayContentDidChange`

(

- `startIdx`
- `removeAmt`
- `addAmt`

)
Ember.Array public

Inherited from Ember.Array: `packages/ember-runtime/lib/mixins/array.js:530`

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

Inherited from Ember.Array: `packages/ember-runtime/lib/mixins/array.js:511`

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

Defined in `packages/ember-runtime/lib/mixins/mutable_array.js:82`

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

Inherited from Ember.Enumerable but overwritten in `packages/ember-runtime/lib/mixins/array.js:587`

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

Inherited from Ember.Array: `packages/ember-runtime/lib/mixins/array.js:364`

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

Defined in `packages/ember-runtime/lib/mixins/mutable_array.js:108`

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

Inherited from Ember.Array: `packages/ember-runtime/lib/mixins/array.js:407`

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

Inherited from Ember.Array: `packages/ember-runtime/lib/mixins/array.js:219`

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

Inherited from Ember.Array: `packages/ember-runtime/lib/mixins/array.js:251`

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

Defined in `packages/ember-runtime/lib/mixins/mutable_array.js:203`

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

Defined in `packages/ember-runtime/lib/mixins/mutable_array.js:159`

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

Defined in `packages/ember-runtime/lib/mixins/mutable_array.js:180`

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

  the objects to add

#### Returns:

Ember.Array:

receiver

### `removeArrayObserver`

(

- `target`
- `opts`

)
Ember.Array public

Inherited from Ember.Array: `packages/ember-runtime/lib/mixins/array.js:484`

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

Defined in `packages/ember-runtime/lib/mixins/mutable_array.js:134`

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

Inherited from Ember.MutableEnumerable but overwritten in `packages/ember-runtime/lib/mixins/mutable_array.js:346`

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

Inherited from Ember.MutableEnumerable: `packages/ember-runtime/lib/mixins/mutable_enumerable.js:105`

Removes each object in the passed enumerable from the receiver.

#### Parameters:

- `objects` Ember.Enumerable
  the objects to remove

#### Returns:

Object: receiver

### `replace`

(

- `idx`
- `amt`
- `objects`

)
public

Defined in `packages/ember-runtime/lib/mixins/mutable_array.js:64`

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

Defined in `packages/ember-runtime/lib/mixins/mutable_array.js:296`

Reverse objects in the array. Works just like `reverse()` but it is KVO-compliant.

#### Returns:

Ember.Array:

receiver

### `setObjects`

(

- `objects`

)
Ember.Array public

Defined in `packages/ember-runtime/lib/mixins/mutable_array.js:315`

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

Defined in `packages/ember-runtime/lib/mixins/mutable_array.js:229`

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

Inherited from Ember.Array: `packages/ember-runtime/lib/mixins/array.js:318`

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

Defined in `packages/ember-runtime/lib/mixins/mutable_array.js:254`

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

Defined in `packages/ember-runtime/lib/mixins/mutable_array.js:275`

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

  the objects to add

#### Returns:

Ember.Array:

receiver

## Properties

### `@each`

Unknown public

Inherited from Ember.Array: `packages/ember-runtime/lib/mixins/array.js:549`

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

Inherited from Ember.Enumerable but overwritten in `packages/ember-runtime/lib/mixins/array.js:275`

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

Inherited from Ember.Array: `packages/ember-runtime/lib/mixins/array.js:500`

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

### `length`

Number public

Inherited from Ember.Array: `packages/ember-runtime/lib/mixins/array.js:208`

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.