Mixin: SC.Array


Extends SC.Enumerable.

This module implements Observer-friendly Array-like behavior. This mixin is picked up by the Array class as well as other controllers, etc. that want to appear to be arrays.

Unlike SC.Enumerable, 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 a KVO-friendly way. You can also be notified whenever the membership if an array changes by changing the syntax of the property to .observes('*myProperty.[]') .

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

Note that the SC.Array mixin also incorporates the SC.Enumerable mixin. All SC.Array-like objects are also enumerable.

Defined in: array.js

Since:
SproutCore 0.9.0

Field Summary

Fields borrowed from SC.Enumerable:
isEnumerable

Instance Methods

Field Detail

isSCArray Boolean
Walk like a duck - use isSCArray to avoid conflicts

Instance Method Detail

addArrayObservers(options)
Parameters:
options
addRangeObserver(indexes, target, method, context)

Creates a new range observer on the receiver. The target/method callback you provide will be invoked anytime any property on the objects in the specified range changes. It will also be invoked if the objects in the range itself changes also.

The callback for a range observer should have the signature:

function rangePropertyDidChange(array, objects, key, indexes, context)

If the passed key is '[]' it means that the object itself changed.

The return value from this method is an opaque reference to the range observer object. You can use this reference to destroy the range observer when you are done with it or to update its range.

Parameters:
indexes SC.IndexSet
indexes to observe
target Object
object to invoke on change
method String|Function
the method to invoke
context Object
optional context
Returns:
SC.RangeObserver
range observer
arrayContentDidChange(start, removedCount, addedCount)
Parameters:
start
removedCount
addedCount
arrayContentWillChange(start, removedCount, addedCount)
Parameters:
start
removedCount
addedCount
compact()

Generates a new array with the contents of the old array, sans any null values.

Returns:
Array
The new, compact array
contains(object)
Returns YES if object is in the array
Parameters:
object Object
to look for
Returns:
Boolean
flatten()

Returns a new array that is a one-dimensional flattening of this array, i.e. for every element of this array extract that and it's elements into a new array.

Returns:
Array
indexOf(object, startAt)
Returns the index for a particular object in the index.
Parameters:
object Object
the item to search for
startAt Number
optional starting location to search, default 0
Returns:
Number
index of -1 if not found
insertAt(idx, object)

This will use the primitive replace() method to insert an object at the specified index.

Parameters:
idx Number
index of insert the object at.
object Object
object to insert
isEqual(ary)
Compares each item in the passed array to this one.
Parameters:
ary Array
The array you want to compare to
Returns:
Boolean
true if they are equal.
lastIndexOf(object, startAt)
Returns the last index for a particular object in the index.
Parameters:
object Object
the item to search for
startAt Number
optional starting location to search, default 0
Returns:
Number
index of -1 if not found
max()

Returns the largest Number in an array of Numbers. Make sure the array only contains values of type Number to get expected result.

Note: This only works for dense arrays.

Returns:
Number
min()

Returns the smallest Number in an array of Numbers. Make sure the array only contains values of type Number to get expected result.

Note: This only works for dense arrays.

Returns:
Number
objectAt(idx)

This is one of the primitives you must implement to support SC.Array. Returns the object at the named index. 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.

Parameters:
idx Number
The index of the item to return. If idx exceeds the current length, return null.
popObject()

Pop object from array or nil if none are left. Works just like pop() but it is KVO-compliant.

Returns:
Object
The popped object
pushObject(object)

Push the object onto the end of the array. Works just like push() but it is KVO-compliant.

Parameters:
object Object
the objects to push
Returns:
Object
The passed object
pushObjects(objects)

Add the objects in the passed numerable to the end of the array. Defers notifying observers of the change until all objects are added.

Parameters:
objects SC.Enumerable
the objects to add
Returns:
SC.Array
receiver
registerDependentKeyWithChain(property, chain)

Register a property chain to propagate to enumerable content.

This will clone the property chain to each item in the enumerable, then save it so that it is automatically set up and torn down when the enumerable content changes.

Parameters:
property String
the property being listened for on this object
chain SC._PropertyChain
the chain to clone to items
removeArrayObservers(options)
Parameters:
options
removeAt(start, length)

Remove an object at the specified index using the replace() primitive method. You can pass either a single index, a start and a length or an index set.

If you pass a single index or a start and length that is beyond the length this method will throw an SC.OUT_OF_RANGE_EXCEPTION

Parameters:
start Number|SC.IndexSet
index, start of range, or index set
length Number
length of passing range
Returns:
Object
receiver
removeDependentKeyWithChain(property, chain)

Removes a dependent key from the enumerable, and tears it down on all content objects.

Parameters:
property String
chain SC._PropertyChain
removeObject(obj)
Search the array of this object, removing any occurrences of it.
Parameters:
obj object
object to remove
removeObjects(objects)

Search the array for the passed set of objects and remove any occurrences of the.

Parameters:
objects SC.Enumerable
the objects to remove
Returns:
SC.Array
receiver
removeRangeObserver(rangeObserver)

Removes a range observer from the receiver. The range observer must already be active on the array.

The return value should replace the old range observer object. It will usually be null.

Parameters:
rangeObserver SC.RangeObserver
the range observer
Returns:
SC.RangeObserver
updated range observer or null
replace(idx, amt, objects)

This is one of the primitives you must implement to support SC.Array. You should replace amt objects started at idx with the objects in the passed array.

Before mutating the underlying data structure, you must call this.arrayContentWillChange(). After the mutation is complete, you must call arrayContentDidChange().

NOTE: JavaScript arrays already implement SC.Array and automatically call the correct callbacks.

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*
setupEnumerablePropertyChains(addedObjects, removedObjects)

For all registered property chains on this object, removed them from objects being removed from the enumerable, and clone them onto newly added objects.

Parameters:
addedObjects Object[]
the objects being added to the enumerable
removedObjects Object[]
the objected being removed from the enumerable
Returns:
Object
receiver
shiftObject()

Shift an object from start of array or nil if none are left. Works just like shift() but it is KVO-compliant.

Returns:
Object
The shifted object
slice(beginIndex, endIndex)

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.

If you don't pass in beginIndex and endIndex, it will act as a copy of the array.

Parameters:
beginIndex
{Integer} (Optional) index to begin slicing from.
endIndex
{Integer} (Optional) index to end the slice at.
Returns:
Array
New array with specified slice
teardownEnumerablePropertyChains(removedObjects)
Parameters:
removedObjects
uniq()

Generates a new array with only unique values from the contents of the old array.

Returns:
Array
The new, de-duped array
unshiftObject(obj)

Unshift an object to start of array. Works just like unshift() but it is KVO-compliant.

Parameters:
obj Object
the object to add
Returns:
Object
The passed object
unshiftObjects(objects)

Adds the named objects to the beginning of the array. Defers notifying observers until all objects have been added.

Parameters:
objects SC.Enumerable
the objects to add
Returns:
SC.Array
receiver
updateRangeObserver(rangeObserver, indexes)

Moves a range observer so that it observes a new range of objects on the array. You must have an existing range observer object from a call to addRangeObserver().

The return value should replace the old range observer object that you pass in.

Parameters:
rangeObserver SC.RangeObserver
the range observer
indexes SC.IndexSet
new indexes to observe
Returns:
SC.RangeObserver
the range observer (or a new one)
without(value)

Generates a new array with the contents of the old array, sans the passed value.

Parameters:
value Object
The value you want to be removed
Returns:
Array
The new, filtered array
Documentation generated by JsDoc Toolkit 2.4.0 on Wed Apr 08 2015 10:02:20 GMT-0600 (CST)