Class: SC.IndexSet


Extends SC.Copyable, SC.Enumerable, SC.Freezable, SC.Observable.

A collection of ranges. You can use an IndexSet to keep track of non- continuous ranges of items in a parent array. IndexSet's are used for selection, for managing invalidation ranges and other data-propagation.

Examples

var set = SC.IndexSet.create(ranges);
  set.contains(index);
  set.add(index, length);
  set.remove(index, length);

  // uses a backing SC.Array object to return each index
  set.forEach(function (object) { .. })

  // returns ranges
  set.forEachRange(function (start, length) { .. });

Implementation Notes

An IndexSet stores indices on the object. A positive value great than the index tells you the end of an occupied range. A negative values tells you the end of an empty range. A value less than the index is a search accelerator. It tells you the start of the nearest range.

Defined in: index_set.js

Since:
SproutCore 1.0

Field Summary

Fields borrowed from SC.Enumerable:
isEnumerable
Fields borrowed from SC.Observable:
isObservable
Fields borrowed from SC.Copyable:
isCopyable
Fields borrowed from SC.Freezable:
isFreezable, isFrozen

Instance Methods

Field Detail

isIndexSet Boolean
Walk like a duck.
length Number
Total number of indexes contained in the set
LOG_OBSERVING Boolean

Usually observing notifications from IndexSet are not useful, so suppress them by default.

max Number

One greater than the largest index currently stored in the set. This is sometimes useful when determining the total range of items covering the index set.

source

Optionally set the source property on an index set and then you can iterate over the actual object values referenced by the index set. See indexOf(), lastIndexOf(), forEachObject(), addObject() and removeObject().

Instance Method Detail

add(start, length)

Adds the specified range of indexes to the set. You can also pass another IndexSet to union the contents of the index set with the receiver.

Parameters:
start Number
Start index, Range, or another IndexSet
length Number Optional, Default: 1
The length of range.
Returns:
SC.IndexSet
receiver
addEach(objects)
Add all the ranges in the passed array.
Parameters:
objects Enumerable
The list of ranges you want to add
addObject(object, firstOnly)

Adds all indexes where the object appears to the set. If firstOnly is passed, then it will find only the first index and add it. If you know the object only appears in the source array one time, firstOnly may make this method faster.

Requires source to work.

Parameters:
object Object
the object to add
firstOnly Boolean
Set to true if you can assume that the first match is the only one
Returns:
SC.IndexSet
receiver
addObjects(objects, firstOnly)

Adds any indexes matching the passed objects. If firstOnly is passed, then only finds the first index for each object.

Parameters:
objects SC.Enumerable
the objects to add
firstOnly Boolean
Set to true if you can assume that the first match is the only one
Returns:
SC.IndexSet
receiver
clear()
Clears the set
clone()
Clones the set into a new set.
contains(start, length)
Returns YES if the index set contains the named index
Parameters:
start Number
index or range
length Number
optional range length
Returns:
Boolean
create(start, length)

To create an empty IndexSet, call create with no arguments. To create a set with one index, call create with one argument: the index to add. To create a fuller set, call create with two arguments: the start index and the length to add.

To create a more complicated set of indices, create an index set and populate individual ranges using .add().

Parameters:
start Number|SC.IndexSet
The start of the range or an index set.
length Number Optional
The length of the range (by default set to 1 if start is a Number)
Returns:
SC.IndexSet
firstObject()
Returns the first index in the set .
forEachIn(start, length, callback, target)

Invokes the callback for each index within the passed start/length range. Otherwise works just like regular forEach().

Parameters:
start Number
starting index
length Number
length of range
callback Function
target Object
Returns:
SC.IndexSet
receiver
forEachObject(callback, target)

Iterates through the objects at each index location in the set. You must have a source property on the set for this to work. The callback you pass will be invoked for each object in the set with the following signature:

function callback(object, index, source, indexSet) { ... }

If you pass a target, it will be used when the callback is called.

Parameters:
callback Function
function to invoke.
target Object
optional content. otherwise uses window
Returns:
SC.IndexSet
receiver
forEachRange(callback, target)

Invoke the callback, passing each occupied range instead of each index. This can be a more efficient way to iterate in some cases. The callback should have the signature:

callback(start, length, indexSet, source) { ... }

If you pass a target as a second option, the callback will be called in the target context.

Parameters:
callback Function
The method to run on each iteration
target Object
the object to call the callback on
Returns:
SC.IndexSet
receiver
indexAfter(index)

Returns the first index in the set after the passed index or null if there are no additional indexes in the set.

Parameters:
index Number
index to check
Returns:
Number
index or -1
indexBefore(index)

Returns the first index in the set before the passed index or null if there are no previous indexes in the set.

Parameters:
index Number
index to check
Returns:
Number
index or -1
indexOf(object, startAt)

Returns the first index in the set that matches the passed object. You must have a source property on the set for this to work.

Parameters:
object Object
the object to check
startAt Number
optional starting point
Returns:
Number
found index or -1 if not in set
inspect()

Returns a string describing the internal range structure. Useful for debugging.

Returns:
String
intersects(start, length)

Returns YES if the index set contains any of the passed indexes. You can pass a single index, a range or an index set.

Parameters:
start Number
index, range, or IndexSet
length Number
optional range length
Returns:
Boolean
isEqual(obj)

Returns YES if the passed index set contains the exact same indexes as the receiver. If you pass any object other than an index set, returns NO.

Parameters:
obj Object
another object.
Returns:
Boolean
lastIndexOf(object, startAt)

Returns the last index in the set that matches the passed object. You must have a source property on the set for this to work.

Parameters:
object Object
the object to check
startAt Number
optional starting point
Returns:
Number
found index or -1 if not in set
lengthIn(start, length)
Total number of indexes within the specified range.
Parameters:
start Number|SC.IndexSet
index, range object or IndexSet
length Number
optional range length
Returns:
Number
count of indexes
min()
The first index included in the set or -1.
rangeStartForIndex(index)

Returns the starting index of the nearest range for the specified index.

Parameters:
index Number
Returns:
Number
starting index
remove(start, length)
Removes the specified range of indexes from the set
Parameters:
start Number
index, Range, or IndexSet
length Number
optional length of range.
Returns:
SC.IndexSet
receiver
removeEach(objects)
Removes all the ranges in the passed array.
Parameters:
objects Object...
The list of objects you want to remove
removeObject(object, firstOnly)

Removes all indexes where the object appears to the set. If firstOnly is passed, then it will find only the first index and add it. If you know the object only appears in the source array one time, firstOnly may make this method faster.

Requires source to work.

Parameters:
object Object
the object to add
firstOnly Boolean
Set to true if you can assume that the first match is the only one
Returns:
SC.IndexSet
receiver
removeObjects(objects, firstOnly)

Removes any indexes matching the passed objects. If firstOnly is passed, then only finds the first index for each object.

Parameters:
objects SC.Enumerable
the objects to add
firstOnly Boolean
Set to true if you can assume that the first match is the only one
Returns:
SC.IndexSet
receiver
replace(start, length)

Replace the index set's current content with the passed index set. This is faster than clearing the index set adding the values again.

Parameters:
start Number
index, Range, or another IndexSet
length Number
optional length of range.
Returns:
SC.IndexSet
receiver
toString()
without(start, length)

Returns a new IndexSet without the passed range or indexes. This is a convenience over simply cloning and removing. Does some optimizations.

Parameters:
start Number
index, range, or IndexSet
length Number
optional range length
Returns:
SC.IndexSet
new index set
Documentation generated by JsDoc Toolkit 2.4.0 on Wed Apr 08 2015 10:02:20 GMT-0600 (CST)