Class: SC.SparseArray


Extends SC.Array, SC.DelegateSupport, SC.Enumerable, SC.Observable.

A dynamically filled array. A SparseArray makes it easy for you to create very large arrays of data but then to defer actually populating that array until it is actually needed. This is often much faster than generating an array up front and paying the cost to load your data then.

Although technically all arrays in JavaScript are "sparse" (in the sense that you can read and write properties at arbitrary indexes), this array keeps track of which elements in the array have been populated already and which ones have not. If you try to get a value at an index that has not yet been populated, the SparseArray will notify a delegate object first, giving the delegate a chance to populate the component.

Most of the time, you will use a SparseArray to incrementally load data from the server. For example, if you have a contact list with 3,000 contacts in it, you may create a SparseArray with a length of 3,000 and set that as the content for a ListView. As the ListView tries to display the visible contacts, it will request them from the SparseArray, which will in turn notify your delegate, giving you a chance to load the contact data from the server.

Defined in: sparse_array.js

Since:
SproutCore 1.0

Field Summary

Fields borrowed from SC.Enumerable:
isEnumerable
Fields borrowed from SC.Array:
isSCArray
Fields borrowed from SC.Observable:
isObservable

Class Methods

Instance Methods

Field Detail

rangeWindowSize Number

The minimum range of elements that should be requested from the delegate. If this value is set to larger than 1, then the sparse array will always fit a requested index into a range of this size and request it.

requestedRangeIndex

This array contains all the start_indexes of ranges requested. This is to avoid calling sparseArrayDidRequestRange to often. Indexes are removed and added as range requests are completed.

Class Method Detail

array(len)

Convenience metohd returns a new sparse array with a default length already provided.

Parameters:
len Number
the length of the array
Returns:
SC.SparseArray

Instance Method Detail

definedIndexes(indexes)

Returns the set of indexes that are currently defined on the sparse array. If you pass an optional index set, the search will be limited to only those indexes. Otherwise this method will return an index set containing all of the defined indexes. Currently this can be quite expensive if you have a lot of indexes defined.

Parameters:
indexes SC.IndexSet
optional from indexes
Returns:
SC.IndexSet
defined indexes
indexOf(obj)

Optimized version of indexOf(). Asks the delegate to provide the index of the specified object. If the delegate does not implement this method then it will search the internal array directly.

Parameters:
obj Object
the object to search for
Returns:
Number
the discovered index or -1 if not found
init()

Make sure to create the index array during init so that it is not shared between all instances.

length()

The length of the sparse array. The delegate for the array should set this length.

objectAt(idx, omitMaterializing)

Returns the object at the specified index. If the value for the index is currently undefined, invokes the didRequestIndex() method to notify the delegate.

The omitMaterializing flag ensures that the object will not be materialized, but it simply checks for the presence of an object at the specified index and will return YES (or undefined if not found). This is useful in the case of SparseArrays, where you might NOT want to request the index to be loaded, but simply need a shallow check to see if the position has been filled.

Parameters:
idx Number
the index to get
omitMaterializing Boolean
Returns:
Object
the object
objectsDidChangeInRange(the)

Invalidates the array content in the specified range. This is not the same as editing an array. Rather it will cause the array to reload the content from the delegate again when it is requested.

Parameters:
the Range
range
Returns:
SC.SparseArray
receiver
provideLength(length)

Call this method from a delegate to provide a length for the sparse array. If you pass null for this property, it will essentially "reset" the array causing your delegate to be called again the next time another object requests the array length.

Parameters:
length Number
the length or null
Returns:
SC.SparseArray
receiver
provideObjectAtIndex(index, the)

Convenience method to provide a single object at a specified index. Under the covers this calls provideObjectsInRange() so you can override only that method and this one will still work.

Parameters:
index Number
the index to insert
the Object
object to insert
Returns:
SC.SparseArray
receiver
provideObjectsInRange(range, array)

This method sets the content for the specified to the objects in the passed array. If you change the way SparseArray implements its internal tracking of objects, you should override this method along with objectAt().

Parameters:
range Range
the range to apply to
array Array
the array of objects to insert
Returns:
SC.SparseArray
receiver
rangeRequestCompleted(start)
Parameters:
start
replace(idx, amt, objects)

Array primitive edits the objects at the specified index unless the delegate rejects the change.

Parameters:
idx Number
the index to begin to replace
amt Number
the number of items to replace
objects Array
the new objects to set instead
Returns:
SC.SparseArray
receiver
requestIndex(idx)

Called by objectAt() whenever you request an index that has not yet been loaded. This will possibly expand the index into a range and then invoke an appropriate method on the delegate to request the data.

It will check if the range has been already requested.

Parameters:
idx Number
the index to retrieve
Returns:
SC.SparseArray
receiver
reset()

Resets the SparseArray, causing it to reload its content from the delegate again.

Returns:
SC.SparseArray
receiver
wasRangeRequested(rangeStart)
Parameters:
rangeStart
Documentation generated by JsDoc Toolkit 2.4.0 on Wed Apr 08 2015 10:02:21 GMT-0600 (CST)