MutableArray
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-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
clearEmber-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.
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
popObjectpublic
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:
-
objects
Ember-Enumerable
- the objects to add
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
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*
reverseObjectsEmber-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
shiftObjectpublic
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
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:
-
objects
Ember-Enumerable
- the objects to add
Returns:
-
Ember-Array
- receiver
[]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
.
Returns:
- this
© 2017 Yehuda Katz, Tom Dale and Ember.js contributors
Licensed under the MIT License.
https://emberjs.com/api/classes/Ember.MutableArray.html