Class EmberArray

This mixin implements Observer-friendly Array-like behavior. It is not a
concrete implementation, but it can be used up by other classes that want
to appear like arrays.

For example, ArrayProxy is a concrete class that can be instantiated to
implement array-like behavior. This class uses the Array Mixin by way of
the MutableArray mixin, which allows observable changes to be made to the
underlying array.

This mixin defines methods specifically for collections that provide
index-ordered access to their contents. When you are designing code that
needs to accept any kind of Array-like object, you should use these methods
instead of Array primitives because these will properly notify observers of
changes to the array.

Although these methods are efficient, they do add a layer of indirection to
your application so it is a good idea to use them only when you need the
flexibility of using both true JavaScript arrays and "virtual" arrays such
as controllers and collections.

You can use the methods defined in this module to access and modify array
contents in an observable-friendly way. You can also be notified whenever
the membership of an array changes by using .observes('myArray.[]').

To support EmberArray in your own class, you must override two
primitives to use it: length() and objectAt().

addArrayObserver
(target, opts)
EmberArraypublic

Optional hash of configuration options including
`willChange` and `didChange` option.

returns

EmberArray

receiver

Adds an array observer to the receiving array. The array observer object
normally must implement two methods:

willChange(observedObj, start, removeCount, addCount) - This method will be
called just before the array is modified.

didChange(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.

The any() method executes the callback function once for each element
present in the array until it finds the one where callback returns a truthy
value (i.e. true). If such an element is found, any() immediately returns
true. Otherwise, any() returns false.

1

function(item, index, array);

item is the current item in the iteration.

index is the current index in the iteration.

array is the array object itself.

Note that in addition to a callback, you can also pass an optional target
object that will be set as this on the context. It can be a good way
to give your iterator function access to an object in cases where an ES6
arrow function would not be appropriate.

If you are implementing an object that supports EmberArray, 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.

arrayContentWillChange
(startIdx, removeAmt, addAmt)
EmberArraypublic

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

EmberArray

receiver

If you are implementing an object that supports EmberArray, 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.

every
(callback, target)
Booleanpublic

Returns true if the passed function returns true for every item in the
enumeration. This corresponds with the Array.prototype.every() method defined in ES5.

The callback method should have the following signature:

1

function(item, index, array);

item is the current item in the iteration.

index is the current index in the iteration.

array is the array itself.

All params are optional. The method should return true or false.

Note that in addition to a callback, you can also pass an optional target
object that will be set as this on the context. This is a good way
to give your iterator function access to the current object.

Note that in addition to a callback, you can pass an optional target object
that will be set as this on the context. This is a good way to give your
iterator function access to the current object. For example:

filterBy
(key, value)
Arraypublic

Filters the array by the property and an optional value. If a value is given, it returns
the items that have said value for the property. If not, it returns all the items that
have a truthy value for the property.

Returns the first item in the array for which the callback returns true.
This method is similar to the find() method defined in ECMAScript 2015.

The callback method you provide should have the following signature (all
parameters are optional):

1

function(item, index, array);

item is the current item in the iteration.

index is the current index in the iteration.

array is the array itself.

It should return the true to include the item in the results, false
otherwise.

Note that in addition to a callback, you can also pass an optional target
object that will be set as this on the context. This is a good way
to give your iterator function access to the current object.

forEach
(callback, target)
Objectpublic

Iterates through the array, calling the passed function on each
item. This method corresponds to the forEach() method defined in
JavaScript 1.6.

The callback method you provide should have the following signature (all
parameters are optional):

1

function(item, index, array);

item is the current item in the iteration.

index is the current index in the iteration.

array is the array itself.

Note that in addition to a callback, you can also pass an optional target
object that will be set as this on the context. This is a good way
to give your iterator function access to the current object.

Used to determine if the array contains the passed object.
Returns true if found, false otherwise.

The optional startAt argument can be used to pass a starting
index to search from, effectively slicing the searchable portion
of the array. If it's negative it will add the array length to
the startAt value passed in as the index to search from. If less
than or equal to -1 * array.length the entire array is searched.

Used to determine the passed object's first occurrence in the array.
Returns the index if found, -1 if no match is found.

The optional startAt argument can be used to pass a starting
index to search from, effectively slicing the searchable portion
of the array. If it's negative it will add the array length to
the startAt value passed in as the index to search from. If less
than or equal to -1 * array.length the entire array is searched.

Note that in addition to a callback, you can also pass an optional target
object that will be set as this on the context. This is a good way
to give your iterator function access to the current object.

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

reject
(callback, target)
Arraypublic

Returns an array with all of the items in the enumeration where the passed
function returns false. This method is the inverse of filter().

The callback method you provide should have the following signature (all
parameters are optional):

1

function(item, index, array);

item is the current item in the iteration.

index is the current index in the iteration

array is the array itself.

It should return a falsey value to include the item in the results.

Note that in addition to a callback, you can also pass an optional target
object that will be set as "this" on the context. This is a good way
to give your iterator function access to the current object.

rejectBy
(key, value)
Arraypublic

Returns an array with the items that do not have truthy values for the provided key.
You can pass an optional second argument with a target value to reject for the key.
Otherwise this will reject objects where the provided property evaluates to false.

setEach
(key, value)
Objectpublic

Sets the value on the named property for each member. This is more
ergonomic than using other methods defined on this helper. If the object
implements Observable, the value will be changed to set(), otherwise
it will be set directly. null objects are skipped.

without
(value)
EmberArraypublic

Returns a new array that excludes the passed value. The default
implementation returns an array regardless of the receiver type.
If the receiver does not contain the value it returns the original array.