W3cubDocs

/Ember.js

Ember.MutableArray Class

PUBLIC

Uses: Ember.Array

Uses: Ember.MutableEnumerable

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

Module: ember-runtime

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.

addObject (obj) Ember.Arraypublic

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

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

clearEmber.Arraypublic

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

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

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

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.

insertAt (idx, object) Ember.Arraypublic

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

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

popObjectpublic

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

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

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

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

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

removeAt (start, len) Ember.Arraypublic

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

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

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

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

replace (idx, amt, objects) public

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

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*

reverseObjectsEmber.Arraypublic

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

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

Returns:

Ember.Array
receiver

setObjects (objects) Ember.Arraypublic

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

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

shiftObjectpublic

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

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

unshiftObject (obj) public

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

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

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

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

[]public

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

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.

Returns:

this

© 2017 Yehuda Katz, Tom Dale and Ember.js contributors
Licensed under the MIT License.
http://emberjs.com/api/classes/Ember.MutableArray.html