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)