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
- definedIndexes(indexes)
- indexOf(obj)
- init()
- length()
- objectAt(idx, omitMaterializing)
- objectsDidChangeInRange(the)
- provideLength(length)
- provideObjectAtIndex(index, the)
- provideObjectsInRange(range, array)
- rangeRequestCompleted(start)
- replace(idx, amt, objects)
- requestIndex(idx)
- reset()
- wasRangeRequested(rangeStart)
Field Detail
rangeWindowSize NumberThe 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.
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
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
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
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
Make sure to create the index array during init so that it is not shared between all instances.
The length of the sparse array. The delegate for the array should set this length.
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.
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
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
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
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
- Parameters:
- start
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
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
Resets the SparseArray, causing it to reload its content from the delegate again.
- Returns:
- SC.SparseArray
- receiver
- Parameters:
- rangeStart