#

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

# Ember.NativeArray Class

Uses

- Ember.MutableArray
- Ember.Observable
- Ember.Copyable

Defined in: `packages/ember-runtime/lib/system/native_array.js:25`
Module: ember-runtime
Parent Module: ember

The NativeArray mixin contains the properties needed to make the native Array support Ember.MutableArray and all of its dependent APIs. Unless you have `EmberENV.EXTEND_PROTOTYPES` or `EmberENV.EXTEND_PROTOTYPES.Array` set to false, this will be applied automatically. Otherwise you can apply the mixin at anytime by calling `Ember.NativeArray.apply(Array.prototype)`.

- Index
- Methods

## Item Index

### Methods

- addObject
- addObserver
- beginPropertyChanges
- cacheFor
- clear
- copy
- decrementProperty
- endPropertyChanges
- frozenCopy deprecated
- get
- getProperties
- getWithDefault
- hasObserverFor
- incrementProperty
- insertAt
- notifyPropertyChange
- popObject
- propertyDidChange
- propertyWillChange
- pushObject
- pushObjects
- removeAt
- removeObject
- removeObserver
- replace
- reverseObjects
- set
- setObjects
- setProperties
- shiftObject
- toggleProperty
- unshiftObject
- unshiftObjects
- willMergeMixin

## Methods

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

### `addObserver`

(

- `key`
- `target`
- `method`

)
public

Inherited from Ember.Observable: `packages/ember-runtime/lib/mixins/observable.js:333`

Adds an observer on a property.

This is the core method used to register an observer for a property.

Once you call this method, any time the key's value is set, your observer will be notified. Note that the observers are triggered any time the value is set, regardless of whether it has actually changed. Your observer should be prepared to handle that.

You can also pass an optional context parameter to this method. The context will be passed to your observer method whenever it is triggered. Note that if you add the same target/method pair on a key multiple times with different context parameters, your observer will only be called once with the last context you passed.

### Observer Methods

Observer methods you pass should generally have the following signature if you do not pass a `context` parameter:

    fooDidChange: function(sender, key, value, rev) { };

The sender is the object that changed. The key is the property that changes. The value property is currently reserved and unused. The rev is the last property revision of the object when it changed, which you can use to detect if the key value has really changed or not.

If you pass a `context` parameter, the context will be passed before the revision like so:

    fooDidChange: function(sender, key, value, context, rev) { };

Usually you will not need the value, context or revision parameters at the end. In this case, it is common to write observer methods that take only a sender and key value as parameters or, if you aren't interested in any of these values, to write an observer that has no parameters at all.

#### Parameters:

- `key` String

  The key to observer

- `target` Object

  The target object to invoke

- `method` String | Function

  The method to invoke.

### `beginPropertyChanges`

() Ember.Observable private

Inherited from Ember.Observable: `packages/ember-runtime/lib/mixins/observable.js:231`

Begins a grouping of property changes.

You can use this method to group property changes so that notifications will not be sent until the changes are finished. If you plan to make a large number of changes to an object at one time, you should call this method at the beginning of the changes to begin deferring change notifications. When you are done making changes, call `endPropertyChanges()` to deliver the deferred change notifications and end deferring.

#### Returns:

Ember.Observable:

### `cacheFor`

(

- `keyName`

)
Object public

Inherited from Ember.Observable: `packages/ember-runtime/lib/mixins/observable.js:490`

Returns the cached value of a computed property, if it exists. This allows you to inspect the value of a computed property without accidentally invoking it if it is intended to be generated lazily.

#### Parameters:

- `keyName` String

#### Returns:

Object:

The cached value of the computed property, if any

### `clear`

() Ember.Array public

Inherited from Ember.MutableArray: `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.

### `copy`

(

- `deep`

)
Object private

Inherited from Ember.Copyable: `packages/ember-runtime/lib/mixins/copyable.js:31`

Required. You must implement this method to apply this mixin.

Override to return a copy of the receiver. Default implementation raises an exception.

#### Parameters:

- `deep` Boolean

  if `true`, a deep copy of the object should be made

#### Returns:

Object:

copy of receiver

### `decrementProperty`

(

- `keyName`
- `decrement`

)
Number public

Inherited from Ember.Observable: `packages/ember-runtime/lib/mixins/observable.js:453`

Set the value of a property to the current value minus some amount.

    player.decrementProperty('lives');
    orc.decrementProperty('health', 5);

#### Parameters:

- `keyName` String

  The name of the property to decrement

- `decrement` Number

  The amount to decrement by. Defaults to 1

#### Returns:

Number:

The new property value

### `endPropertyChanges`

() Ember.Observable private

Inherited from Ember.Observable: `packages/ember-runtime/lib/mixins/observable.js:251`

Ends a grouping of property changes.

You can use this method to group property changes so that notifications will not be sent until the changes are finished. If you plan to make a large number of changes to an object at one time, you should call `beginPropertyChanges()` at the beginning of the changes to defer change notifications. When you are done making changes, call this method to deliver the deferred change notifications and end deferring.

#### Returns:

Ember.Observable:

### `frozenCopy`

() Object deprecated private

Inherited from Ember.Copyable: `packages/ember-runtime/lib/mixins/copyable.js:44`

Deprecated: Use `Object.freeze` instead.

If the object implements `Ember.Freezable`, then this will return a new copy if the object is not frozen and the receiver if the object is frozen.

Raises an exception if you try to call this method on a object that does not support freezing.

You should use this method whenever you want a copy of a freezable object since a freezable object can simply return itself without actually consuming more memory.

#### Returns:

Object:

copy of receiver or receiver

### `get`

(

- `keyName`

)
Object public

Inherited from Ember.Observable: `packages/ember-runtime/lib/mixins/observable.js:96`

Retrieves the value of a property from the object.

This method is usually similar to using `object[keyName]` or `object.keyName`, however it supports both computed properties and the unknownProperty handler.

Because `get` unifies the syntax for accessing all these kinds of properties, it can make many refactorings easier, such as replacing a simple property with a computed property, or vice versa.

### Computed Properties

Computed properties are methods defined with the `property` modifier declared at the end, such as:

    fullName: Ember.computed('firstName', 'lastName', function() {
      return this.get('firstName') + ' ' + this.get('lastName');
    })

When you call `get` on a computed property, the function will be called and the return value will be returned instead of the function itself.

### Unknown Properties

Likewise, if you try to call `get` on a property whose value is `undefined`, the `unknownProperty()` method will be called on the object. If this method returns any value other than `undefined`, it will be returned instead. This allows you to implement "virtual" properties that are not defined upfront.

#### Parameters:

- `keyName` String

  The property to retrieve

#### Returns:

Object:

The property value or undefined.

### `getProperties`

(

- `list`

)
Object public

Inherited from Ember.Observable: `packages/ember-runtime/lib/mixins/observable.js:139`

To get the values of multiple properties at once, call `getProperties` with a list of strings or an array:

    record.getProperties('firstName', 'lastName', 'zipCode');
    // { firstName: 'John', lastName: 'Doe', zipCode: '10011' }

is equivalent to:

    record.getProperties(['firstName', 'lastName', 'zipCode']);
    // { firstName: 'John', lastName: 'Doe', zipCode: '10011' }

#### Parameters:

- `list` String... | Array

  of keys to get

#### Returns:

Object:

### `getWithDefault`

(

- `keyName`
- `defaultValue`

)
Object public

Inherited from Ember.Observable: `packages/ember-runtime/lib/mixins/observable.js:415`

Retrieves the value of a property, or a default value in the case that the property returns `undefined`.

    person.getWithDefault('lastName', 'Doe');

#### Parameters:

- `keyName` String

  The name of the property to retrieve

- `defaultValue` Object

  The value to return if the property value is undefined

#### Returns:

Object:

The property value or the defaultValue.

### `hasObserverFor`

(

- `key`

)
Boolean private

Inherited from Ember.Observable: `packages/ember-runtime/lib/mixins/observable.js:400`

Returns `true` if the object currently has observers registered for a particular key. You can use this method to potentially defer performing an expensive action until someone begins observing a particular property on the object.

#### Parameters:

- `key` String

  Key to check

#### Returns:

Boolean:

### `incrementProperty`

(

- `keyName`
- `increment`

)
Number public

Inherited from Ember.Observable: `packages/ember-runtime/lib/mixins/observable.js:433`

Set the value of a property to the current value plus some amount.

    person.incrementProperty('age');
    team.incrementProperty('score', 2);

#### Parameters:

- `keyName` String

  The name of the property to increment

- `increment` Number

  The amount to increment by. Defaults to 1

#### Returns:

Number:

The new property value

### `insertAt`

(

- `idx`
- `object`

)
Ember.Array public

Inherited from Ember.MutableArray: `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

### `notifyPropertyChange`

(

- `keyName`

)
Ember.Observable public

Inherited from Ember.Observable: `packages/ember-runtime/lib/mixins/observable.js:318`

Convenience method to call `propertyWillChange` and `propertyDidChange` in succession.

#### Parameters:

- `keyName` String

  The property key to be notified about.

#### Returns:

Ember.Observable:

### `popObject`

() public

Inherited from Ember.MutableArray: `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

### `propertyDidChange`

(

- `keyName`

)
Ember.Observable private

Inherited from Ember.Observable: `packages/ember-runtime/lib/mixins/observable.js:294`

Notify the observer system that a property has just changed.

Sometimes you need to change a value directly or indirectly without actually calling `get()` or `set()` on it. In this case, you can use this method and `propertyWillChange()` instead. Calling these two methods together will notify all observers that the property has potentially changed value.

Note that you must always call `propertyWillChange` and `propertyDidChange` as a pair. If you do not, it may get the property change groups out of order and cause notifications to be delivered more often than you would like.

#### Parameters:

- `keyName` String

  The property key that has just changed.

#### Returns:

Ember.Observable:

### `propertyWillChange`

(

- `keyName`

)
Ember.Observable private

Inherited from Ember.Observable: `packages/ember-runtime/lib/mixins/observable.js:270`

Notify the observer system that a property is about to change.

Sometimes you need to change a value directly or indirectly without actually calling `get()` or `set()` on it. In this case, you can use this method and `propertyDidChange()` instead. Calling these two methods together will notify all observers that the property has potentially changed value.

Note that you must always call `propertyWillChange` and `propertyDidChange` as a pair. If you do not, it may get the property change groups out of order and cause notifications to be delivered more often than you would like.

#### Parameters:

- `keyName` String

  The property key that is about to change.

#### Returns:

Ember.Observable:

### `pushObject`

(

- `obj`

)
public

Inherited from Ember.MutableArray: `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

Inherited from Ember.MutableArray: `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

### `removeAt`

(

- `start`
- `len`

)
Ember.Array public

Inherited from Ember.MutableArray: `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

### `removeObserver`

(

- `key`
- `target`
- `method`

)
public

Inherited from Ember.Observable: `packages/ember-runtime/lib/mixins/observable.js:385`

Remove an observer you have previously registered on this object. Pass the same key, target, and method you passed to `addObserver()` and your target will no longer receive notifications.

#### Parameters:

- `key` String

  The key to observer

- `target` Object

  The target object to invoke

- `method` String | Function

  The method to invoke.

### `replace`

(

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

)
public

Inherited from Ember.MutableArray: `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

Inherited from Ember.MutableArray: `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

### `set`

(

- `keyName`
- `value`

)
Object public

Inherited from Ember.Observable: `packages/ember-runtime/lib/mixins/observable.js:164`

Sets the provided key or path to the value.

    record.set("key", value);

This method is generally very similar to calling `object["key"] = value` or `object.key = value`, except that it provides support for computed properties, the `setUnknownProperty()` method and property observers.

### Computed Properties

If you try to set a value on a key that has a computed property handler defined (see the `get()` method for an example), then `set()` will call that method, passing both the value and key instead of simply changing the value itself. This is useful for those times when you need to implement a property that is composed of one or more member properties.

### Unknown Properties

If you try to set a value on a key that is undefined in the target object, then the `setUnknownProperty()` handler will be called instead. This gives you an opportunity to implement complex "virtual" properties that are not predefined on the object. If `setUnknownProperty()` returns undefined, then `set()` will simply set the value on the object.

### Property Observers

In addition to changing the property, `set()` will also register a property change with the object. Unless you have placed this call inside of a `beginPropertyChanges()` and `endPropertyChanges(),` any "local" observers (i.e. observer methods declared on the same object), will be called immediately. Any "remote" observers (i.e. observer methods declared on another object) will be placed in a queue and called at a later time in a coalesced manner.

#### Parameters:

- `keyName` String

  The property to set

- `value` Object

  The value to set or `null`.

#### Returns:

Object:

The passed value

### `setObjects`

(

- `objects`

)
Ember.Array public

Inherited from Ember.MutableArray: `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

### `setProperties`

(

- `hash`

)
Object public

Inherited from Ember.Observable: `packages/ember-runtime/lib/mixins/observable.js:213`

Sets a list of properties at once. These properties are set inside a single `beginPropertyChanges` and `endPropertyChanges` batch, so observers will be buffered.

    record.setProperties({ firstName: 'Charles', lastName: 'Jolley' });

#### Parameters:

- `hash` Object

  the hash of keys and values to set

#### Returns:

Object:

The passed in hash

### `shiftObject`

() public

Inherited from Ember.MutableArray: `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

### `toggleProperty`

(

- `keyName`

)
Boolean public

Inherited from Ember.Observable: `packages/ember-runtime/lib/mixins/observable.js:473`

Set the value of a boolean property to the opposite of its current value.

    starship.toggleProperty('warpDriveEngaged');

#### Parameters:

- `keyName` String

  The name of the property to toggle

#### Returns:

Boolean:

The new property value

### `unshiftObject`

(

- `obj`

)
public

Inherited from Ember.MutableArray: `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

Inherited from Ember.MutableArray: `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

### `willMergeMixin`

() private

Inherited from Ember.Copyable: `packages/ember-runtime/lib/mixins/controller_content_model_alias_deprecation.js:21`

Available since 1.4.0