sproutit-sproutcore 1.0.0.20090416161445 → 1.0.0.20090720093355

data/frameworks/sproutcore/frameworks/runtime/private/chain_observer.js

@@ -31,14 +31,14 @@ SC._ChainObserver = function(property) {
 } ;
 
 // This is the primary entry point.  Configures the chain.
-SC._ChainObserver.createChain = function(rootObject, path, target, method) {
+SC._ChainObserver.createChain = function(rootObject, path, target, method, context) {
 
-  var parts = path.split('.') ;
-  
   // First we create the chain.
-  var root ;
-  var tail = root = new SC._ChainObserver(parts[0]) ;
-  var len = parts.length;
+  var parts = path.split('.'),
+      root  = new SC._ChainObserver(parts[0]),
+      tail  = root,
+      len   = parts.length;
+
   for(var idx=1;idx<len;idx++) {
     tail = tail.next = new SC._ChainObserver(parts[idx]) ;
   }
@@ -50,7 +50,7 @@ SC._ChainObserver.createChain = function(rootObject, path, target, method) {
   
   // Finally, set the target/method on the tail so that future changes will
   // trigger.
-  tail.target = target; tail.method = method ;
+  tail.target = target; tail.method = method ; tail.context = context ;
   
   // and return the root to save
   return root ;
@@ -108,10 +108,16 @@ SC._ChainObserver.prototype = {
     if (this.next) this.next.objectDidChange(value) ;
     
     // if we have a target/method, call it.
-    var target = this.target; var method = this.method;
+    var target  = this.target,
+        method  = this.method,
+        context = this.context ;
     if (target && method) {
-      var rev = object.propertyRevision ;
-      method.call(target, object, property, value, rev) ;
+      var rev = object ? object.propertyRevision : null ;
+      if (context) {
+        method.call(target, object, property, value, context, rev);
+      } else {
+        method.call(target, object, property, value, rev) ;
+      }
     } 
   },
   
@@ -128,7 +134,7 @@ SC._ChainObserver.prototype = {
     if (this.next) this.next.destroyChain() ;
     
     // and clear left overs...
-    this.next = this.target = this.method = this.object = null ;
+    this.next = this.target = this.method = this.object = this.context = null;
     return null ;
   }
   

data/frameworks/sproutcore/frameworks/runtime/private/observer_queue.js

@@ -63,24 +63,61 @@ SC.Observers = {
     }
   },
   
+  // Range Observers register here to indicate that they may potentially 
+  // need to start observing.
+  addPendingRangeObserver: function(observer) {
+    var ro = this.rangeObservers;
+    if (!ro) ro = this.rangeObservers = SC.CoreSet.create();
+    ro.add(observer);
+    return this ;
+  },
+  
+  _TMP_OUT: [],
+  
   // Flush the queue.  Attempt to add any saved observers.
-  flush: function() {
+  flush: function(object) { 
+       
+    // flush any observers that we tried to setup but didn't have a path yet
     var oldQueue = this.queue ;
-    var newQueue = (this.queue = []) ; 
-    var idx = oldQueue.length ;
-    while(--idx >= 0) {
-      var item = oldQueue[idx] ;
-      if (!item) continue ;
+    if (oldQueue && oldQueue.length > 0) {
+      var newQueue = (this.queue = []) ; 
+      var idx = oldQueue.length ;
+      while(--idx >= 0) {
+        var item = oldQueue[idx] ;
+        if (!item) continue ;
+
+        var tuple = SC.tupleForPropertyPath(item[0], item[3]);
+        if (tuple) {
+          tuple[0].addObserver(tuple[1], item[1], item[2]) ;
+        } else newQueue.push(item) ;
+      }
+    }
+    
+    // if this object needsRangeObserver then see if any pending range 
+    // observers need it.
+    if (object._kvo_needsRangeObserver) {
+      var set = this.rangeObservers,
+          len = set ? set.get('length') : 0,
+          out = this._TMP_OUT,
+          ro;
+          
+      for(idx=0;idx<len;idx++) {
+        ro = set[idx]; // get the range observer
+        if (ro.setupPending(object)) {
+          out.push(ro); // save to remove later
+        }
+      }
       
-      var tuple = SC.tupleForPropertyPath(item[0], item[3]);
-      if (tuple) {
-        tuple[0].addObserver(tuple[1], item[1], item[2]) ;
-      } else newQueue.push(item) ;
+      // remove any that have setup
+      if (out.length > 0) set.removeEach(out);
+      out.length = 0; // reset
+      object._kvo_needsRangeObserver = NO ;
     }
+    
   },
   
-  isObserveringSuspended: 0,
-  _pending: SC.Set.create(),
+  isObservingSuspended: 0,
+  _pending: SC.CoreSet.create(),
   
   objectHasPendingChanges: function(obj) {
     this._pending.add(obj) ; // save for later
@@ -97,10 +134,13 @@ SC.Observers = {
     var pending ;
     if(--this.isObservingSuspended <= 0) {
       pending = this._pending ;
-      this._pending = SC.Set.create() ;
-      while(pending.length > 0) {
-        pending.pop()._notifyPropertyObservers() ;
+      this._pending = SC.CoreSet.create() ;
+      
+      var idx, len = pending.length;
+      for(idx=0;idx<len;idx++) {
+        pending[idx]._notifyPropertyObservers() ;
       }
+      pending.clear();
       pending = null ;
     }
   }

data/frameworks/sproutcore/frameworks/runtime/private/observer_set.js

@@ -21,19 +21,27 @@ SC._ObserverSet = {
   
   // adds the named target/method observer to the set.  The method must be
   // a function, not a string..
-  add: function(target, method) {
+  add: function(target, method, context) {
     var targetGuid = (target) ? SC.guidFor(target) : "__this__";
     
     // get the set of methods
     var methods = this[targetGuid] ;
     if (!methods) {
-      methods = this[targetGuid] = SC.Set.create() ;
+      methods = this[targetGuid] = SC.CoreSet.create() ;
       methods.target = target ;
       methods.isTargetSet = YES ; // used for getMembers().
       this.targets++ ;
     }
-    
     methods.add(method) ;
+    
+    // context is really useful sometimes but not used that often so this
+    // implementation is intentionally lazy.
+    if (context !== undefined) {
+      var contexts = methods.contexts ;
+      if (!context) contexts = {};
+      contexts[SC.guidFor(method)] = context ;
+    }
+    
     this._membersCacheIsValid = NO ;
   },
   
@@ -53,16 +61,21 @@ SC._ObserverSet = {
     if (methods.length <= 0) {
       methods.target = null;
       methods.isTargetSet = NO ;
+      methods.contexts = null ;
       delete this[targetGuid] ;
       this.targets-- ;
+      
+    } else if (methods.contexts) {
+      delete methods.contexts[SC.guidFor(method)];
     }
-    
+
     this._membersCacheIsValid = NO;
     
     return YES ;
   },
   
   // Invokes the target/method pairs in the receiver.  Used by SC.RunLoop
+  // Note: does not support context
   invokeMethods: function() {
     // iterate through the set, look for sets.
     for(var key in this) {
@@ -93,7 +106,17 @@ SC._ObserverSet = {
       if (value && value.isTargetSet) {
         var idx = value.length;
         var target = value.target ;
-        while(--idx>=0) ret.push([target, value[idx]]) ;
+        
+        // slightly slower - only do if we have contexts
+        var contexts = value.contexts ;
+        if (contexts) {
+          while(--idx>=0) {
+            var method = value[idx] ;
+            ret.push([target, method, contexts[SC.guidFor(method)]]) ;
+          }
+        } else {
+          while(--idx>=0) ret.push([target, value[idx]]);
+        }
       }
     }
 
@@ -110,6 +133,7 @@ SC._ObserverSet = {
       if (oldSet && oldSet.isTargetSet) {
         newSet = oldSet.clone();
         newSet.target = oldSet.target ;
+        if (oldSet.contexts) newSet.contexts = SC.clone(oldSet.contexts);
         ret[key] = newSet ;
       }
     }

data/frameworks/sproutcore/frameworks/runtime/protocols/observable_protocol.js

@@ -0,0 +1,40 @@
+// ==========================================================================
+// Project:   SproutCore Costello - Property Observing Library
+// Copyright: ©2006-2009 Sprout Systems, Inc. and contributors.
+//            Portions ©2008-2009 Apple, Inc. All rights reserved.
+// License:   Licened under MIT license (see license.js)
+// ==========================================================================
+
+/**
+  The SC.ObservableProtocol defines optional methods you can implement on your
+  objects.  They will be used if defined but are not required for observing to
+  work.
+*/
+SC.ObservableProtocol = {
+  
+  /**  
+    Generic property observer called whenever a property on the receiver 
+    changes.
+    
+    If you need to observe a large number of properties on your object, it
+    is sometimes more efficient to implement this observer only and then to
+    handle requests yourself.  Although this observer will be triggered 
+    more often than an observer registered on a specific property, it also
+    does not need to be registered which can make it faster to setup your 
+    object instance.
+    
+    You will often implement this observer using a switch statement on the
+    key parameter, taking appropriate action. 
+    
+    @param observer {null} no longer used; usually null
+    @param target {Object} the target of the change.  usually this
+    @param key {String} the name of the property that changed
+    @param value {Object} the new value of the property.
+    @param revision {Number} a revision you can use to quickly detect changes.
+    @returns {void}
+  */
+  propertyObserver: function(observer,target,key,value, revision) {
+    
+  }
+  
+};

data/frameworks/sproutcore/frameworks/runtime/system/binding.js

@@ -12,7 +12,7 @@ require('system/object') ;
   the console.  This should be disabled in production code.  Note that you
   can also enable this from the console or temporarily.
 */
-SC.LOG_BINDING_NOTIFICATIONS = NO ;
+SC.LOG_BINDINGS = NO ;
 
 /**
   Performance paramter.  This will benchmark the time spent firing each 
@@ -334,6 +334,7 @@ SC.Binding = {
     if (this.isConnected) return this ;
     this.isConnected = YES ;
     this._connectionPending = YES ; // its connected but not really...    
+    this._syncOnConnect = YES ;
     SC.Binding._connectQueue.add(this) ;
     return this; 
   },
@@ -424,7 +425,7 @@ SC.Binding = {
     the binding as dirty if the value has changed.
   */
   fromPropertyDidChange: function(target, key) {
-    var v = target.get(key) ;
+    var v = target ? target.get(key) : null;
 
     //console.log("fromPropertyDidChange: %@ v = %@".fmt(this, v)) ;
     
@@ -432,7 +433,7 @@ SC.Binding = {
     // schedule to register an update.
     if (v !== this._bindingValue) {
 
-      this._setBindingValue(v) ;
+      this._setBindingValue(target, key) ;
       this._changePending = YES ;
       SC.Binding._changeQueue.add(this) ; // save for later.  
     }
@@ -456,14 +457,32 @@ SC.Binding = {
     // if the new value is different from the current binding value, then 
     // schedule to register an update.
     if (v !== this._transformedBindingValue) {
-      this._setBindingValue(v) ;
+      this._setBindingValue(target, key) ;
       this._changePending = YES ;
       SC.Binding._changeQueue.add(this) ; // save for later.  
     }
   },
   
-  _setBindingValue: function(v) {
-    this._bindingValue = v ;
+  /**
+    Saves the source location for the binding value.  This will be used later
+    to actually update the binding value.
+  */
+  _setBindingValue: function(source, key) {
+    this._bindingSource = source;
+    this._bindingKey    = key;
+  },
+  
+  /**
+    Updates the binding value from the current binding source if needed.  This
+    should be called just before using this._bindingValue.
+  */
+  _computeBindingValue: function() {
+    var source = this._bindingSource,
+        key    = this._bindingKey,
+        v;
+        
+    if (!source) return ; // nothing to do
+    this._bindingValue = v = source.getPath(key);
     
     // apply any transforms to get the to property value also
     var transforms = this._transforms;
@@ -482,10 +501,10 @@ SC.Binding = {
     this._transformedBindingValue = v;
   },
   
-  _connectQueue: SC.Set.create(),
-  _alternateConnectQueue: SC.Set.create(),
-  _changeQueue: SC.Set.create(),
-  _alternateChangeQueue: SC.Set.create(),
+  _connectQueue: SC.CoreSet.create(),
+  _alternateConnectQueue: SC.CoreSet.create(),
+  _changeQueue: SC.CoreSet.create(),
+  _alternateChangeQueue: SC.CoreSet.create(),
   _changePending: NO,
 
   /**
@@ -498,9 +517,10 @@ SC.Binding = {
     // don't allow flushing more than one at a time
     if (this._isFlushing) return NO; 
     this._isFlushing = YES ;
+    SC.Observers.suspendPropertyObserving();
 
     var didFlush = NO ;
-    var log = SC.LOG_BINDING_NOTIFICATIONS ;
+    var log = SC.LOG_BINDINGS ;
     
     // connect any bindings
     var queue, binding ;
@@ -534,6 +554,8 @@ SC.Binding = {
     
     // clean up
     this._isFlushing = NO ;
+    SC.Observers.resumePropertyObserving();
+
     return didFlush ;
   },
   
@@ -546,11 +568,12 @@ SC.Binding = {
 
     // compute the binding targets if needed.
     this._computeBindingTargets() ;
+    this._computeBindingValue();
     
     var v = this._bindingValue ;
     var tv = this._transformedBindingValue ;
     var bench = SC.BENCHMARK_BINDING_NOTIFICATIONS ;
-    var log = SC.LOG_BINDING_NOTIFICATIONS ; 
+    var log = SC.LOG_BINDINGS ; 
     
     // the from property value will always be the binding value, update if 
     // needed.
@@ -601,7 +624,7 @@ SC.Binding = {
       // if the new value is different from the current binding value, then 
       // schedule to register an update.
       if (v !== this._bindingValue) {
-        this._setBindingValue(v) ;
+        this._setBindingValue(target, key) ;
         this._changePending = YES ;
         SC.Binding._changeQueue.add(this) ; // save for later.  
       }
@@ -773,8 +796,9 @@ SC.Binding = {
       placeholder = SC.MULTIPLE_PLACEHOLDER ;
     }
     return this.from(fromPath).transform(function(value, isForward) {
-      if (SC.isArray(value)) {
-        value = (value.length>1) ? placeholder : (value.length<=0) ? null : (value.objectAt ? value.objectAt(0) : value[0]);
+      if (value && value.isEnumerable) {
+        var len = value.get('length');
+        value = (len>1) ? placeholder : (len<=0) ? null : value.firstObject();
       }
       return value ;
     }) ;

data/frameworks/sproutcore/frameworks/runtime/system/index_set.js

@@ -0,0 +1,1166 @@
+// ==========================================================================
+// Project:   SproutCore Costello - Property Observing Library
+// Copyright: ©2006-2009 Sprout Systems, Inc. and contributors.
+//            Portions ©2008-2009 Apple, Inc. All rights reserved.
+// License:   Licened under MIT license (see license.js)
+// ==========================================================================
+
+sc_require('mixins/enumerable') ;
+sc_require('mixins/observable') ;
+sc_require('mixins/freezable');
+sc_require('mixins/copyable');
+
+/**
+  @class 
+
+  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-propogation.
+
+  h2. 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 the index
+    set.forEachIndex(function(index) { ... });
+    
+    // returns ranges
+    set.forEachRange(function(start, length) { .. });
+  }}}
+
+  h2. 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.
+
+  @extends Object
+  @extends SC.Enumerable 
+  @extends SC.Observable
+  @extends SC.Copyable
+  @extends SC.Freezable
+  @since SproutCore 1.0
+*/
+SC.IndexSet = SC.mixin({}, 
+  SC.Enumerable, SC.Observable, SC.Freezable, SC.Copyable,
+/** @scope SC.IndexSet.prototype */ {
+
+  /** @private
+    Walks a content array and copies its contents to a new array.  For large
+    content arrays this is faster than using slice()
+  */
+  _sc_sliceContent: function(c) {
+    if (c.length < 1000) return c.slice(); // use native when faster
+    var cur = 0, ret = [], next = c[0];
+    while(next !== 0) {
+      ret[cur] = next ;
+      cur = (next<0) ? (0-next) : next ;
+      next = c[cur];
+    }
+    ret[cur] = 0;
+    this._hint(0, cur, ret); // hints are not copied manually - add them
+    return ret ;
+  },
+  
+  /**
+    To create a set, pass either a start and index or another IndexSet.
+  */
+  create: function(start, length) { 
+    var ret = SC.beget(this);
+    ret.initObservable();
+    
+    // optimized method to clone an index set.
+    if (start && start.isIndexSet) {
+      ret._content = this._sc_sliceContent(start._content);
+      ret.max = start.max;
+      ret.length = start.length; 
+      ret.source = start.source ;
+      
+    // otherwise just do a regular add
+    } else {
+      ret._content = [0];
+      if (start !== undefined) ret.add(start, length);
+    }
+    return ret ;
+  },
+
+  isIndexSet: YES,
+  
+  HINT_SIZE: 256,
+  
+  /**
+    Total number of indexes contained in the set
+
+    @type number
+  */
+  length: 0,
+  
+  /**
+    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.
+  */
+  max: 0,
+  
+  /**
+    The first index included in the set or -1.
+    
+    @property
+    @type {Number}
+  */
+  min: function() {  
+    var content = this._content, 
+        cur = content[0];
+    return (cur === 0) ? -1 : (cur>0) ? 0 : Math.abs(cur);
+    
+  }.property('[]').cacheable(),
+  
+  firstObject: function() {
+    return (this.get('length')>0) ? this.get('min') : undefined;  
+  }.property(),
+  
+  /** 
+    Returns the starting index of the nearest range for the specified 
+    index.
+    
+    @param {Number} index
+    @returns {Number} starting index
+  */
+  rangeStartForIndex: function(index) {    
+    var content = this._content,
+        max     = this.get('max'),
+        ret, next, accel;
+    
+    // fast cases
+    if (index >= max) return max ;
+    if (Math.abs(content[index]) > index) return index ; // we hit a border
+    
+    // use accelerator to find nearest content range
+    accel = index - (index % SC.IndexSet.HINT_SIZE);
+    ret = content[accel];
+    if (ret<0 || ret>index) ret = accel;
+    next = Math.abs(content[ret]);
+
+    // now step forward through ranges until we find one that includes the
+    // index.
+    while (next < index) {
+      ret = next ;
+      next = Math.abs(content[ret]);
+    }
+    return ret ;
+  },
+    
+  /**
+    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.
+    
+    @param {Object} obj another object.
+    @returns {Boolean}
+  */
+  isEqual: function(obj) {
+    
+    // optimize for some special cases
+    if (obj === this) return YES ;
+    if (!obj || !obj.isIndexSet || (obj.max !== this.max) || (obj.length !== this.length)) return NO;
+
+    // ok, now we need to actually compare the ranges of the two.
+    var lcontent = this._content,
+        rcontent = obj._content,
+        cur      = 0,
+        next     = lcontent[cur];
+    
+    do {
+      if (rcontent[cur] !== next) return NO ;
+      cur = Math.abs(next) ;
+      next = lcontent[cur];
+    } while (cur !== 0);
+    return YES ;
+  },
+  
+  /**
+    Returns the first index in the set before the passed index or null if 
+    there are no previous indexes in the set.
+    
+    @param {Number} index index to check
+    @returns {Number} index or -1
+  */
+  indexBefore: function(index) {
+    
+    if (index===0) return -1; // fast path
+    index--; // start with previous index
+    
+    var content = this._content, 
+        max     = this.get('max'),
+        start   = this.rangeStartForIndex(index);
+    if (!content) return null;
+
+    // loop backwards until we find a range that is in the set.
+    while((start===max) || (content[start]<0)) {
+      if (start === 0) return -1 ; // nothing before; just quit
+      index = start -1 ;
+      start = this.rangeStartForIndex(index);
+    }
+    
+    return index;
+  },
+
+  /**
+    Returns the first index in the set after the passed index or null if 
+    there are no additional indexes in the set.
+    
+    @param {Number} index index to check
+    @returns {Number} index or -1
+  */
+  indexAfter: function(index) {
+    var content = this._content,
+        max     = this.get('max'),
+        start, next ;
+    if (!content || (index>=max)) return -1; // fast path
+    index++; // start with next index
+    
+
+    // loop forwards until we find a range that is in the set.
+    start = this.rangeStartForIndex(index);
+    next  = content[start];
+    while(next<0) {
+      if (next === 0) return -1 ; //nothing after; just quit
+      index = start = Math.abs(next);
+      next  = content[start];
+    }
+    
+    return index;
+  },
+  
+  /**
+    Returns YES if the index set contains the named index
+    
+    @param {Number} start index or range
+    @param {Number} length optional range length
+    @returns {Boolean}
+  */
+  contains: function(start, length) {
+    var content, cur, next, rstart, rnext;
+    
+    // normalize input
+    if (length === undefined) { 
+      if (start === null || start === undefined) return NO ;
+      
+      if (typeof start === SC.T_NUMBER) {
+        length = 1 ;
+        
+      // if passed an index set, check each receiver range
+      } else if (start && start.isIndexSet) {
+        if (start === this) return YES ; // optimization
+
+        content = start._content ;
+        cur = 0 ;
+        next = content[cur];
+        while (next !== 0) {
+          if ((next>0) && !this.contains(cur, next-cur)) return NO ;
+          cur = Math.abs(next);
+          next = content[cur];
+        }
+        return YES ;
+        
+      } else {
+        length = start.length; 
+        start = start.start;
+      }
+    }
+    
+    rstart = this.rangeStartForIndex(start);
+    rnext  = this._content[rstart];
+    
+    return (rnext>0) && (rstart <= start) && (rnext >= (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.
+    
+    @param {Number} start index, range, or IndexSet
+    @param {Number} length optional range length
+    @returns {Boolean}
+  */
+  intersects: function(start, length) {
+    var content, cur, next, lim;
+    
+    // normalize input
+    if (length === undefined) { 
+      if (typeof start === SC.T_NUMBER) {
+        length = 1 ;
+        
+      // if passed an index set, check each receiver range
+      } else if (start && start.isIndexSet) {
+        if (start === this) return YES ; // optimization
+
+        content = start._content ;
+        cur = 0 ;
+        next = content[cur];
+        while (next !== 0) {
+          if ((next>0) && this.intersects(cur, next-cur)) return YES ;
+          cur = Math.abs(next);
+          next = content[cur];
+        }
+        return NO ;
+        
+      } else {
+        length = start.length; 
+        start = start.start;
+      }
+    }
+    
+    cur     = this.rangeStartForIndex(start);
+    content = this._content;
+    next    = content[cur];
+    lim     = start + length;
+    while (cur < lim) {
+      if (next === 0) return NO; // no match and at end!
+      if ((next > 0) && (next > start)) return YES ; // found a match
+      cur = Math.abs(next);
+      next = content[cur];
+    }
+    return NO ; // no match
+  },
+
+  /**
+    Returns a new IndexSet without the passed range or indexes.   This is a
+    convenience over simply cloning and removing.  Does some optimizations.
+    
+    @param {Number} start index, range, or IndexSet
+    @param {Number} length optional range length
+    @returns {SC.IndexSet} new index set
+  */
+  without: function(start, length) {
+    if (start === this) return SC.IndexSet.create(); // just need empty set
+    return this.clone().remove(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.
+    
+    @param {Number} start index, Range, or another IndexSet
+    @param {Number} length optional length of range. 
+    @returns {SC.IndexSet} receiver
+  */
+  replace: function(start, length) {
+    
+    if (length === undefined) {
+      if (typeof start === SC.T_NUMBER) {
+        length = 1 ;
+      } else if (start && start.isIndexSet) {
+        this._content = this._sc_sliceContent(start._content);
+        this.beginPropertyChanges()
+          .set('max', start.max)
+          .set('length', start.length)
+          .set('source', start.source)
+          .enumerableContentDidChange()
+        .endPropertyChanges();
+        return this ;
+        
+      } else {
+        length = start.length;
+        start  = start.start;
+      }
+    }
+    
+    var oldlen = this.length;
+    this._content.length=1;
+    this._content[0] = 0;
+    this.length = this.max = 0 ; // reset without notifying since add()
+    return this.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.
+    
+    @param {Number} start index, Range, or another IndexSet
+    @param {Number} length optional length of range. 
+    @returns {SC.IndexSet} receiver
+  */
+  add: function(start, length) {
+    
+    if (this.isFrozen) throw SC.FROZEN_ERROR;
+    
+    var content, cur, next;
+
+    // normalize IndexSet input
+    if (start && start.isIndexSet) {
+      
+      content = start._content;
+      
+      if (!content) return this; // nothing to do
+
+      cur = 0 ;
+      next = content[0];
+      while(next !== 0) {
+        if (next>0) this.add(cur, next-cur);
+        cur = next<0 ? 0-next : next;
+        next = content[cur];
+      }
+      return this ;
+      
+    } else if (length === undefined) { 
+      
+      if (start === null || start === undefined) {
+        return this; // nothing to do
+      } else if (typeof start === SC.T_NUMBER) {
+        length = 1 ;
+      } else {
+        length = start.length; 
+        start = start.start;
+      }
+    } else if (length === null) length = 1 ;
+
+    // special case - appending to end of set
+    var max     = this.get('max'),
+        oldmax  = max,
+        delta, value ;
+
+    content = this._content ;
+    
+    if (start === max) {
+
+      // if adding to the end and the end is in set, merge.
+      if (start > 0) {
+        cur = this.rangeStartForIndex(start-1);
+        next = content[cur];
+        
+        // just extend range at end
+        if (next > 0) { 
+          delete content[max]; // no 0
+          content[cur] = max = start + length ;
+          start = cur ;
+          
+        // previous range was not in set, just tack onto the end
+        } else {
+          content[max] = max = start + length;
+        }
+      } else {
+        content[start] = max = length;
+      }
+      
+      content[max] = 0 ;
+      this.set('max', max);
+      this.set('length', this.length + length) ;
+      length = max - start ;
+      
+    } else if (start > max) {
+      content[max] = 0-start; // empty!
+      content[start] = start+length ;
+      content[start+length] = 0; // set end
+      this.set('max', start + length) ;
+      this.set('length', this.length + length) ;
+      
+      // affected range goes from starting range to end of content.
+      length = start + length - max ;
+      start = max ;
+      
+    // otherwise, merge into existing range
+    } else {
+
+      // find nearest starting range.  split or join that range
+      cur   = this.rangeStartForIndex(start);
+      next  = content[cur];
+      max   = start + length ;
+      delta = 0 ;
+
+      // we are right on a boundary and we had a range or were the end, then
+      // go back one more.
+      if ((start>0) && (cur === start) && (next <= 0)) {
+        cur = this.rangeStartForIndex(start-1);
+        next = content[cur] ;
+      }
+      
+      // previous range is not in set.  splice it here
+      if (next < 0) { 
+        content[cur] = 0-start ;
+        
+        // if previous range extends beyond this range, splice afterwards also
+        if (Math.abs(next) > max) {
+          content[start] = 0-max;
+          content[max] = next ;
+        } else content[start] = next;
+        
+      // previous range is in set.  merge the ranges
+      } else {
+        start = cur ;
+        if (next > max) {
+          delta -= next - max ;
+          max = next ;
+        }
+      }
+      
+      // at this point there should be clean starting point for the range.
+      // just walk the ranges, adding up the length delta and then removing
+      // the range until we find a range that passes last
+      cur = start;
+      while (cur < max) {
+        // get next boundary.  splice if needed - if value is 0, we are at end
+        // just skip to last
+        value = content[cur];
+        if (value === 0) {
+          content[max] = 0;
+          next = max ;
+          delta += max - cur ;
+        } else {
+          next  = Math.abs(value);
+          if (next > max) {
+            content[max] = value ;
+            next = max ;
+          }
+
+          // ok, cur range is entirely inside top range.  
+          // add to delta if needed
+          if (value < 0) delta += next - cur ;
+        }
+
+        delete content[cur] ; // and remove range
+        cur = next;
+      }
+      
+      // cur should always === last now.  if the following range is in set,
+      // merge in also - don't adjust delta because these aren't new indexes
+      if ((cur = content[max]) > 0) {
+        delete content[max];     
+        max = cur ;
+      }
+
+      // finally set my own range.
+      content[start] = max ;
+      if (max > oldmax) this.set('max', max) ;
+
+      // adjust length
+      this.set('length', this.get('length') + delta);
+      
+      // compute hint range
+      length = max - start ;
+    }
+    
+    this._hint(start, length);
+    if (delta !== 0) this.enumerableContentDidChange();
+    return this;
+  },
+
+  /**
+    Removes the specified range of indexes from the set
+    
+    @param {Number} start index, Range, or IndexSet
+    @param {Number} length optional length of range. 
+    @returns {SC.IndexSet} receiver
+  */
+  remove: function(start, length) {
+
+    if (this.isFrozen) throw SC.FROZEN_ERROR;
+    
+    // normalize input
+    if (length === undefined) { 
+      if (start === null || start === undefined) {
+        return this; // nothing to do
+
+      } else if (typeof start === SC.T_NUMBER) {
+        length = 1 ;
+      
+      // if passed an index set, just add each range in the index set.
+      } else if (start.isIndexSet) {
+        start.forEachRange(this.remove, this);
+        return this;
+
+      } else {
+        length = start.length; 
+        start = start.start;
+      }
+    }
+
+    // special case - appending to end of set
+    var max     = this.get('max'),
+        oldmax  = max,
+        content = this._content,
+        cur, next, delta, value, last ;
+
+    // if we're past the end, do nothing.
+    if (start >= max) return this;
+
+    // find nearest starting range.  split or join that range
+    cur   = this.rangeStartForIndex(start);
+    next  = content[cur];
+    last  = start + length ;
+    delta = 0 ;
+
+    // we are right on a boundary and we had a range or were the end, then
+    // go back one more.
+    if ((start>0) && (cur === start) && (next > 0)) {
+      cur = this.rangeStartForIndex(start-1);
+      next = content[cur] ;
+    }
+    
+    // previous range is in set.  splice it here
+    if (next > 0) { 
+      content[cur] = start ;
+      
+      // if previous range extends beyond this range, splice afterwards also
+      if (next > last) {
+        content[start] = last;
+        content[last] = next ;
+      } else content[start] = next;
+      
+    // previous range is not in set.  merge the ranges
+    } else {
+      start = cur ;
+      next  = Math.abs(next);
+      if (next > last) {
+        last = next ;
+      }
+    }
+    
+    // at this point there should be clean starting point for the range.
+    // just walk the ranges, adding up the length delta and then removing
+    // the range until we find a range that passes last
+    cur = start;
+    while (cur < last) {
+      // get next boundary.  splice if needed - if value is 0, we are at end
+      // just skip to last
+      value = content[cur];
+      if (value === 0) {
+        content[last] = 0;
+        next = last ;
+
+      } else {
+        next  = Math.abs(value);
+        if (next > last) {
+          content[last] = value ;
+          next = last ;
+        }
+
+        // ok, cur range is entirely inside top range.  
+        // add to delta if needed
+        if (value > 0) delta += next - cur ;
+      }
+
+      delete content[cur] ; // and remove range
+      cur = next;
+    }
+    
+    // cur should always === last now.  if the following range is not in set,
+    // merge in also - don't adjust delta because these aren't new indexes
+    if ((cur = content[last]) < 0) {
+      delete content[last];     
+      last = Math.abs(cur) ;
+    }
+
+    // set my own range - if the next item is 0, then clear it.
+    if (content[last] === 0) {
+      delete content[last];
+      content[start] = 0 ;
+      this.set('max', start); //max has changed
+      
+    } else {
+      content[start] = 0-last ;
+    }
+
+    // adjust length
+    this.set('length', this.get('length') - delta);
+    
+    // compute hint range
+    length = last - start ;
+    
+    this._hint(start, length);
+    if (delta !== 0) this.enumerableContentDidChange();
+    return this;
+  },
+    
+  /** @private 
+    iterates through a named range, setting hints every HINT_SIZE indexes 
+    pointing to the nearest range start.  The passed range must start on a
+    range boundary.  It can end anywhere.
+  */
+  _hint: function(start, length, content) {
+    if (content === undefined) content = this._content;
+    
+    var skip    = SC.IndexSet.HINT_SIZE,
+        next    = Math.abs(content[start]), // start of next range
+        loc     = start - (start % skip) + skip, // next hint loc
+        lim     = start + length ; // stop
+        
+    while (loc < lim) {
+      // make sure we are in current rnage
+      while ((next !== 0) && (next <= loc)) {
+        start = next ; 
+        next  = Math.abs(content[start]) ;
+      }
+      
+      // past end
+      if (next === 0) {
+        delete content[loc];
+
+      // do not change if on actual boundary
+      } else if (loc !== start) {
+        content[loc] = start ;  // set hint
+      }
+      
+      loc += skip;
+    }
+  },
+
+  /**
+    Clears the set 
+  */
+  clear: function() {
+    if (this.isFrozen) throw SC.FROZEN_ERROR;
+    
+    var oldlen = this.length;
+    this._content.length=1;
+    this._content[0] = 0;
+    this.set('length', 0).set('max', 0);
+    if (oldlen > 0) this.enumerableContentDidChange();
+  },
+  
+  /**
+    Add all the ranges in the passed array.
+  */
+  addEach: function(objects) {
+    if (this.isFrozen) throw SC.FROZEN_ERROR;
+
+    var idx = objects.get('length') ;
+    if (objects.objectAt) {
+      while(--idx >= 0) this.add(objects.objectAt(idx)) ;
+    } else {
+      while(--idx >= 0) this.add(objects[idx]) ;
+    }
+    return this ;
+  },  
+
+  /**
+    Removes all the ranges in the passed array.
+  */
+  removeEach: function(objects) {
+    if (this.isFrozen) throw SC.FROZEN_ERROR;
+
+    var idx = objects.get('length') ;
+    if (objects.objectAt) {
+      while(--idx >= 0) this.remove(objects.objectAt(idx)) ;
+    } else {
+      while(--idx >= 0) this.remove(objects[idx]) ;
+    }
+    return this ;
+  },  
+
+  /**
+   Clones the set into a new set.  
+  */
+  clone: function() {
+    return SC.IndexSet.create(this);    
+  },
+  
+  /**
+    Returns a string describing the internal range structure.  Useful for
+    debugging.
+    
+    @returns {String}
+  */
+  inspect: function() {
+    var content = this._content,
+        len     = content.length,
+        idx     = 0,
+        ret     = [],
+        item;
+    
+    for(idx=0;idx<len;idx++) {
+      item = content[idx];
+      if (item !== undefined) ret.push("%@:%@".fmt(idx,item));      
+    }
+    return "SC.IndexSet<%@>".fmt(ret.join(' , '));
+  },
+  
+  /** 
+    Invoke the callback, passing each occuppied 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.
+    
+    @param {Function} callback the iterator callback
+    @param {Object} target the target
+    @returns {SC.IndexSet} receiver
+  */
+  forEachRange: function(callback, target) {
+    var content = this._content,
+        cur     = 0,
+        next    = content[cur],
+        source  = this.source;
+
+    if (target === undefined) target = null ;
+    while (next !== 0) {
+      if (next > 0) callback.call(target, cur, next - cur, this, source);
+      cur  = Math.abs(next);
+      next = content[cur];
+    }
+    
+    return this ;
+  },    
+  
+  /**
+    Invokes the callback for each index within the passed start/length range.
+    Otherwise works just like regular forEach().
+    
+    @param {Number} start starting index
+    @param {Number} length length of range
+    @param {Function} callback
+    @param {Object} target
+    @returns {SC.IndexSet} receiver
+  */
+  forEachIn: function(start, length, callback, target) {
+    var content = this._content,
+        cur     = 0,
+        idx     = 0,
+        lim     = start + length,
+        source  = this.source,
+        next    = content[cur];
+
+    if (target === undefined) target = null ;
+    while (next !== 0) {
+      if (cur < start) cur = start ; // skip forward 
+      while((cur < next) && (cur < lim)) { 
+        callback.call(target, cur++, idx++, this, source); 
+      }
+      
+      if (cur >= lim) {
+        cur = next = 0 ;
+      } else {
+        cur  = Math.abs(next);
+        next = content[cur];
+      }
+    }
+    return this ;
+  },
+
+  /**
+    Total number of indexes within the specified range.
+    
+    @param {Number|SC.IndexSet} start index, range object or IndexSet
+    @param {Number} length optional range length
+    @returns {Number} count of indexes
+  */
+  lengthIn: function(start, length) {
+
+    var ret = 0 ;
+    
+    // normalize input
+    if (length === undefined) { 
+      if (start === null || start === undefined) {
+        return 0; // nothing to do
+
+      } else if (typeof start === SC.T_NUMBER) {
+        length = 1 ;
+        
+      // if passed an index set, just add each range in the index set.
+      } else if (start.isIndexSet) {
+        start.forEachRange(function(start, length) { 
+          ret += this.lengthIn(start, length);
+        }, this);
+        return ret;
+        
+      } else {
+        length = start.length; 
+        start = start.start;
+      }
+    }
+
+    // fast path
+    if (this.get('length') === 0) return 0;
+    
+    var content = this._content,
+        cur     = 0,
+        next    = content[cur],
+        lim     = start + length ;
+
+    while (cur<lim && next !== 0) {
+      if (next>0) {
+        ret += (next>lim) ? lim-cur : next-cur;
+      }
+      cur  = Math.abs(next);
+      next = content[cur];
+    }
+    
+    return ret ;
+  },
+  
+  // ..........................................................
+  // OBJECT API
+  // 
+  
+  /**
+    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().
+  */
+  source: null,
+  
+  /**
+    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.
+    
+    @param {Object} object the object to check 
+    @param {Number} startAt optional starting point
+    @returns {Number} found index or -1 if not in set
+  */
+  indexOf: function(object, startAt) {
+    var source  = this.source;
+    if (!source) throw "%@.indexOf() requires source".fmt(this);
+    
+    var len     = source.get('length'),
+        
+        // start with the first index in the set
+        content = this._content,
+        cur     = content[0]<0 ? Math.abs(content[0]) : 0,
+        idx ;
+        
+    while(cur>=0 && cur<len) {
+      idx = source.indexOf(object, cur);
+      if (idx<0) return -1 ; // not found in source
+      if (this.contains(idx)) return idx; // found in source and in set.
+      cur = idx+1;
+    } 
+    
+    return -1; // not found
+  },
+
+  /**
+    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.
+    
+    @param {Object} object the object to check 
+    @param {Number} startAt optional starting point
+    @returns {Number} found index or -1 if not in set
+  */
+  lastIndexOf: function(object, startAt) {
+    var source  = this.source;
+    if (!source) throw "%@.lastIndexOf() requires source".fmt(this);
+    
+    // start with the last index in the set
+    var len     = source.get('length'),
+        cur     = this.max-1,
+        idx ;
+
+    if (cur >= len) cur = len-1;
+    while (cur>=0) {
+      idx = source.lastIndexOf(object, cur);
+      if (idx<0) return -1 ; // not found in source
+      if (this.contains(idx)) return idx; // found in source and in set.
+      cur = idx+1;
+    } 
+    
+    return -1; // not found
+  },
+  
+  /**
+    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.
+    
+    @param {Function} callback function to invoke.  
+    @param {Object} target optional content. otherwise uses window
+    @returns {SC.IndexSet} receiver
+  */ 
+  forEachObject: function(callback, target) {
+    var source  = this.source;
+    if (!source) throw "%@.forEachObject() requires source".fmt(this);
+
+    var content = this._content,
+        cur     = 0,
+        idx     = 0,
+        next    = content[cur];
+        
+    if (target === undefined) target = null ;
+    while (next !== 0) {
+      
+      while(cur < next) { 
+        callback.call(target, source.objectAt(cur), cur, source, this); 
+        cur++;
+      }
+      
+      cur  = Math.abs(next);
+      next = content[cur];
+    }
+    return this ;
+  },
+  
+  /**
+    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.
+    
+    @param {Object} object the object to add
+    @returns {SC.IndexSet} receiver
+  */
+  addObject: function(object, firstOnly) {
+    var source  = this.source;
+    if (!source) throw "%@.addObject() requires source".fmt(this);
+
+    var len = source.get('length'),
+        cur = 0, idx;
+        
+    while(cur>=0 && cur<len) {
+      idx = source.indexOf(object, cur);
+      if (idx >= 0) { 
+        this.add(idx);
+        if (firstOnly) return this ;
+        cur = idx++;
+      } else return this ;
+    }
+    return this ;    
+  },
+
+  /**
+    Adds any indexes matching the passed objects.  If firstOnly is passed, 
+    then only finds the first index for each object.
+    
+    @param {SC.Enumerable} objects the objects to add
+    @returns {SC.IndexSet} receiver
+  */
+  addObjects: function(objects, firstOnly) {
+    objects.forEach(function(object) {
+      this.addObject(object, firstOnly);
+    }, this);
+    return this;
+  },
+  
+  /**
+    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.
+    
+    @param {Object} object the object to add
+    @returns {SC.IndexSet} receiver
+  */
+  removeObject: function(object, firstOnly) {
+    var source  = this.source;
+    if (!source) throw "%@.removeObject() requires source".fmt(this);
+
+    var len = source.get('length'),
+        cur = 0, idx;
+        
+    while(cur>=0 && cur<len) {
+      idx = source.indexOf(object, cur);
+      if (idx >= 0) { 
+        this.remove(idx);
+        if (firstOnly) return this ;
+        cur = idx+1;
+      } else return this ;
+    }
+    return this ;    
+  },
+
+  /**
+    Removes any indexes matching the passed objects.  If firstOnly is passed, 
+    then only finds the first index for each object.
+    
+    @param {SC.Enumerable} objects the objects to add
+    @returns {SC.IndexSet} receiver
+  */
+  removeObjects: function(objects, firstOnly) {
+    objects.forEach(function(object) {
+      this.removeObject(object, firstOnly);
+    }, this);
+    return this;
+  },
+  
+  
+  // .......................................
+  // PRIVATE 
+  //
+
+  /** 
+    Usually observing notifications from IndexSet are not useful, so 
+    supress them by default.
+  */
+  LOG_OBSERVING: NO,
+  
+  /** @private - optimized call to forEach() */
+  forEach: function(callback, target) {
+    var content = this._content,
+        cur     = 0,
+        idx     = 0,
+        source  = this.source,
+        next    = content[cur];
+
+    if (target === undefined) target = null ;
+    while (next !== 0) {
+      while(cur < next) { 
+        callback.call(target, cur++, idx++, this, source); 
+      }
+      cur  = Math.abs(next);
+      next = content[cur];
+    }
+    return this ;
+  },
+  
+  /** @private - support iterators */
+  nextObject: function(ignore, idx, context) {
+    var content = this._content,
+        next    = context.next,
+        max     = this.get('max'); // next boundary
+    
+    // seed.
+    if (idx === null) {
+      idx = next = 0 ;
+
+    } else if (idx >= max) {
+      delete context.next; // cleanup context
+      return null ; // nothing left to do
+
+    } else idx++; // look on next index
+    
+    // look for next non-empty range if needed.
+    if (idx === next) {
+      do { 
+        idx = Math.abs(next);
+        next = content[idx];
+      } while(next < 0);
+      context.next = next;
+    }
+    
+    return idx;
+  },
+  
+  toString: function() {
+    var str = [];
+    this.forEachRange(function(start, length) {
+      str.push(length === 1 ? start : "%@..%@".fmt(start, start + length - 1));
+    }, this);
+    return "SC.IndexSet<%@>".fmt(str.join(',')) ;
+  },
+  
+  max: 0
+
+}) ;
+
+SC.IndexSet.slice = SC.IndexSet.copy = SC.IndexSet.clone ;
+SC.IndexSet.EMPTY = SC.IndexSet.create().freeze();