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
- addArrayObservers(options)
- addRangeObserver(indexes, target, method, context)
- arrayContentDidChange(start, removedCount, addedCount)
- arrayContentWillChange(start, removedCount, addedCount)
- compact()
- contains(object)
- flatten()
- indexOf(object, startAt)
- insertAt(idx, object)
- isEqual(ary)
- lastIndexOf(object, startAt)
- max()
- min()
- objectAt(idx)
- popObject()
- pushObject(object)
- pushObjects(objects)
- registerDependentKeyWithChain(property, chain)
- removeArrayObservers(options)
- removeAt(start, length)
- removeDependentKeyWithChain(property, chain)
- removeObject(obj)
- removeObjects(objects)
- removeRangeObserver(rangeObserver)
- replace(idx, amt, objects)
- setupEnumerablePropertyChains(addedObjects, removedObjects)
- shiftObject()
- slice(beginIndex, endIndex)
- teardownEnumerablePropertyChains(removedObjects)
- uniq()
- unshiftObject(obj)
- unshiftObjects(objects)
- updateRangeObserver(rangeObserver, indexes)
- without(value)
Field Detail
isSCArray BooleanInstance Method Detail
- Parameters:
- options
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
- Parameters:
- start
- removedCount
- addedCount
- Parameters:
- start
- removedCount
- addedCount
Generates a new array with the contents of the old array, sans any null values.
- Returns:
- Array
- The new, compact array
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
- 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
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
- 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
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
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
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.
Pop object from array or nil if none are left. Works just like pop() but it is KVO-compliant.
- Returns:
- Object
- The popped object
Push the object onto the end of the array. Works just like push() but it is KVO-compliant.
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
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
- Parameters:
- options
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
Removes a dependent key from the enumerable, and tears it down on all content objects.
- Parameters:
- property String
- chain SC._PropertyChain
- Parameters:
- obj object
- object to remove
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
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
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*
For all registered property chains on this object, removed them from objects being removed from the enumerable, and clone them onto newly added objects.
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
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
- Parameters:
- removedObjects
Generates a new array with only unique values from the contents of the old array.
- Returns:
- Array
- The new, de-duped array
Unshift an object to start of array. Works just like unshift() but it is KVO-compliant.
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
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)