sproutit-sproutcore 1.0.20090721145236 → 1.0.20090721145251

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

@@ -0,0 +1,375 @@
+// ==========================================================================
+// 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');
+
+// IMPORTANT NOTE:  This file actually defines two classes: 
+// SC.Set is a fully observable set class documented below. 
+// SC._CoreSet is just like SC.Set but is not observable.  This is required
+// because SC.Observable is built on using sets and requires sets without 
+// observability.
+//
+// We use pointer swizzling below to swap around the actual definitions so 
+// that the documentation will turn out right.  (The docs should only 
+// define SC.Set - not SC._CoreSet)
+
+/**
+  @class 
+
+  An unordered collection of objects.
+
+  A Set works a bit like an array except that its items are not ordered.  
+  You can create a set to efficiently test for membership for an object. You 
+  can also iterate through a set just like an array, even accessing objects
+  by index, however there is no gaurantee as to their order.
+
+  Note that SC.Set is a primitive object, like an array.  It does implement
+  limited key-value observing support but it does not extend from SC.Object
+  so you should not subclass it.
+
+  h1. Creating a Set
+
+  You can create a set like you would most objects using SC.Set.create().  
+  Most new sets you create will be empty, but you can also initialize the set 
+  with some content by passing an array or other enumerable of objects to the 
+  constructor.
+
+  Finally, you can pass in an existing set and the set will be copied.  You
+  can also create a copy of a set by calling SC.Set#clone().
+
+  {{{
+    // creates a new empty set
+    var foundNames = SC.Set.create();
+
+    // creates a set with four names in it.
+    var names = SC.Set.create(["Charles", "Peter", "Chris", "Erich"]) ;
+
+    // creates a copy of the names set.
+    var namesCopy = SC.Set.create(names);
+
+    // same as above.
+    var anotherNamesCopy = names.clone();
+  }}}
+
+  h1. Adding/Removing Objects
+
+  You generally add or removed objects from a set using add() or remove().
+  You can add any type of object including primitives such as numbers,
+  strings, and booleans.
+
+  Note that objects can only exist one time in a set.  If you call add() on
+  a set with the same object multiple times, the object will only be added 
+  once.  Likewise, calling remove() with the same object multiple times will
+  remove the object the first time and have no effect on future calls until 
+  you add the object to the set again.
+
+  Note that you cannot add/remove null or undefined to a set.  Any attempt to
+  do so will be ignored.  
+
+  In addition to add/remove you can also call push()/pop().  Push behaves just
+  like add() but pop(), unlike remove() will pick an arbitrary object, remove
+  it and return it.  This is a good way to use a set as a job queue when you
+  don't care which order the jobs are executed in.
+
+  h1. Testing for an Object
+
+  To test for an object's presence in a set you simply call SC.Set#contains().
+  This method tests for the object's hash, which is generally the same as the
+  object's _guid but if you implement the hash() method on the object, it will
+  use the return value from that method instead.
+
+  @extends SC.Enumerable 
+  @extends SC.Observable
+  @extends SC.Copyable
+  @extends SC.Freezable
+
+  @since SproutCore 1.0
+*/
+SC.Set = SC.mixin({}, 
+  SC.Enumerable, 
+  SC.Observable, 
+  SC.Freezable, 
+/** @scope SC.Set.prototype */ {
+
+  /** 
+    Creates a new set, with the optional array of items included in the 
+    return set.
+
+    @param {SC.Enumerable} items items to add
+    @return {SC.Set}
+  */
+  create: function(items) {
+    var ret, idx, pool = SC.Set._pool, isObservable = this.isObservable;
+    if (!isObservable && items===undefined && pool.length>0) ret = pool.pop();
+    else {
+      ret = SC.beget(this);
+      if (isObservable) ret.initObservable();
+      
+      if (items && items.isEnumerable && items.get('length')>0) {
+
+        ret.isObservable = NO; // suspend change notifications
+        
+        // arrays and sets get special treatment to make them a bit faster
+        if (items.isSCArray) {
+          idx = items.get ? items.get('length') : items.length;
+          while(--idx>=0) ret.add(items.objectAt(idx));
+        
+        } else if (items.isSet) {
+          idx = items.length;
+          while(--idx>=0) ret.add(items[idx]);
+          
+        // otherwise use standard SC.Enumerable API
+        } else items.forEach(function(i) { ret.add(i); }, this);
+        
+        ret.isObservable = isObservable;
+      }
+    }
+    return ret ;
+  },
+  
+  isSet: YES,
+  
+  /**
+    This property will change as the number of objects in the set changes.
+
+    @type number
+  */
+  length: 0,
+
+  firstObject: function() {
+    return (this.length>0) ? this[0] : undefined ;
+  }.property(),
+  
+  /**
+    Clears the set 
+  */
+  clear: function() { 
+    if (this.isFrozen) throw SC.FROZEN_ERROR;
+    this.length = 0;
+    return this ;
+  },
+
+  /**
+    Call this method to test for membership.
+  */
+  contains: function(obj) {
+
+    // because of the way a set is "reset", the guid for an object may 
+    // still be stored as a key, but points to an index that is beyond the
+    // length.  Therefore the found idx must both be defined and less than
+    // the current length.
+    if (obj === null) return NO ;
+    var idx = this[SC.hashFor(obj)] ;
+    return (!SC.none(idx) && (idx < this.length) && (this[idx]===obj)) ;
+  },
+  
+  /**
+    Returns YES if the passed object is also a set that contains the same 
+    objects as the receiver.
+  
+    @param {SC.Set} obj the other object
+    @returns {Boolean}
+  */
+  isEqual: function(obj) {
+    // fail fast
+    if (!obj || !obj.isSet || (obj.get('length') !== this.get('length'))) {
+      return NO ;
+    }
+    
+    var loc = this.get('length');
+    while(--loc>=0) {
+      if (!obj.contains(this[loc])) return NO ;
+    }
+    
+    return YES;
+  },
+
+  /**
+    Call this method to add an object. performs a basic add.
+
+    If the object is already in the set it will not be added again.
+
+    @param obj {Object} the object to add
+    @returns {Object} this
+  */
+  add: function(obj) {
+    if (this.isFrozen) throw SC.FROZEN_ERROR;
+    
+    // cannot add null to a set.
+    if (obj===null || obj===undefined) return this; 
+
+    var guid = SC.hashFor(obj) ;
+    var idx = this[guid] ;
+    var len = this.length ;
+    if ((idx===null || idx===undefined) || (idx >= len) || (this[idx]!==obj)){
+      this[len] = obj ;
+      this[guid] = len ;
+      this.length = len+1;
+    }
+    
+    if (this.isObservable) this.enumerableContentDidChange();
+    
+    return this ;
+  },
+
+  /**
+    Add all the items in the passed array or enumerable
+  */
+  addEach: function(objects) {
+    if (this.isFrozen) throw SC.FROZEN_ERROR;
+    if (!objects || !objects.isEnumerable) {
+      throw "%@.addEach must pass enumerable".fmt(this);
+    }
+
+    var idx, isObservable = this.isObservable ;
+    
+    if (isObservable) this.beginPropertyChanges();
+    if (objects.isSCArray) {
+      idx = objects.get('length');
+      while(--idx >= 0) this.add(objects.objectAt(idx)) ;
+    } else if (objects.isSet) {
+      idx = objects.length;
+      while(--idx>=0) this.add(objects[idx]);
+      
+    } else objects.forEach(function(i) { this.add(i); }, this);
+    if (isObservable) this.endPropertyChanges();
+    
+    return this ;
+  },  
+
+  /**
+    Removes the object from the set if it is found.
+
+    If the object is not in the set, nothing will be changed.
+
+    @param obj {Object} the object to remove
+    @returns {this} this
+  */  
+  remove: function(obj) {
+    if (this.isFrozen) throw SC.FROZEN_ERROR;
+
+    if (SC.none(obj)) return this ;
+    var guid = SC.hashFor(obj);
+    var idx = this[guid] ;
+    var len = this.length;
+
+    // not in set.
+    if (SC.none(idx) || (idx >= len) || (this[idx] !== obj)) return this; 
+
+    // clear the guid key
+    delete this[guid] ;
+
+    // to clear the index, we will swap the object stored in the last index.
+    // if this is the last object, just reduce the length.
+    if (idx < (len-1)) {
+      obj = this[idx] = this[len-1];
+      this[SC.hashFor(obj)] = idx ;
+    }
+
+    // reduce the length
+    this.length = len-1;
+    if (this.isObservable) this.enumerableContentDidChange();
+    return this ;
+  },
+
+  /**
+    Removes an arbitrary object from the set and returns it.
+
+    @returns {Object} an object from the set or null
+  */
+  pop: function() {
+    if (this.isFrozen) throw SC.FROZEN_ERROR;
+    var obj = (this.length > 0) ? this[this.length-1] : null ;
+    if (obj) this.remove(obj) ;
+    return obj ;
+  },
+
+  /**
+    Removes all the items in the passed array.
+  */
+  removeEach: function(objects) {
+    if (this.isFrozen) throw SC.FROZEN_ERROR;
+    if (!objects || !objects.isEnumerable) {
+      throw "%@.addEach must pass enumerable".fmt(this);
+    }
+
+    var idx, isObservable = this.isObservable ;
+    
+    if (isObservable) this.beginPropertyChanges();
+    if (objects.isSCArray) {
+      idx = objects.get('length');
+      while(--idx >= 0) this.remove(objects.objectAt(idx)) ;
+    } else if (objects.isSet) {
+      idx = objects.length;
+      while(--idx>=0) this.remove(objects[idx]);
+    } else objects.forEach(function(i) { this.remove(i); }, this);
+    if (isObservable) this.endPropertyChanges();
+    
+    return this ;
+  },  
+
+  /**
+   Clones the set into a new set.  
+  */
+  clone: function() {
+    return this.constructor.create(this);    
+  },
+
+  /**
+    Return a set to the pool for reallocation.
+  */
+  destroy: function() {
+    this.isFrozen = NO ; // unfreeze to return to pool
+    if (!this.isObservable) SC.Set._pool.push(this.clear());
+    return this;
+  },
+  
+  // .......................................
+  // PRIVATE 
+  //
+
+  // optimized
+  forEach: function(iterator, target) {
+    var len = this.length;
+    if (!target) target = this ;
+    for(var idx=0;idx<len;idx++) iterator.call(target, this[idx], idx, this);
+    return this ;
+  },
+
+  toString: function() {
+    var len = this.length, idx, ary = [];
+    for(idx=0;idx<len;idx++) ary[idx] = this[idx];
+    return "SC.Set<%@>".fmt(ary.join(',')) ;
+  },
+  
+  // the pool used for non-observable sets
+  _pool: [],
+  
+  isObservable: YES
+
+}) ;
+
+SC.Set.constructor = SC.Set;
+
+// Make SC.Set look a bit more like other enumerables
+SC.Set.copy = SC.Set.clone ;
+SC.Set.push = SC.Set.unshift = SC.Set.add ;
+SC.Set.shift = SC.Set.pop ;
+
+// add generic add/remove enumerable support
+SC.Set.addObject = SC.Set.add ;
+SC.Set.removeObject = SC.Set.remove;
+
+SC.Set._pool = [];
+
+// CoreSet is like Set but not observable
+SC.CoreSet = SC.beget(SC.Set);
+SC.CoreSet.isObservable = NO ;
+SC.CoreSet.constructor = SC.CoreSet;

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

@@ -0,0 +1,295 @@
+// ==========================================================================
+// 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/array') ;
+sc_require('mixins/observable') ;
+sc_require('mixins/delegate_support') ;
+
+/**
+  @class
+
+  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 are 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.
+  
+  @extends SC.Enumerable
+  @extends SC.Array
+  @extends SC.Observable
+  @extends SC.DelegateSupport
+  @since SproutCore 1.0
+*/
+
+SC.SparseArray = SC.Object.extend(SC.Observable, SC.Enumerable, SC.Array, 
+  SC.DelegateSupport, /** @scope SC.SparseArray.prototype */ {  
+
+  // ..........................................................
+  // LENGTH SUPPORT
+  // 
+
+  _requestingLength: 0,  
+  _requestingIndex: 0,
+   
+  /**
+    The length of the sparse array.  The delegate for the array should set 
+    this length.
+    
+    @property {Number}
+  */
+  length: function() {
+    var del = this.delegate ;
+    if (del && SC.none(this._length) && del.sparseArrayDidRequestLength) {
+      this._requestingLength++ ;
+      del.sparseArrayDidRequestLength(this);
+      this._requestingLength-- ;
+    }
+    return this._length || 0 ;
+  }.property().cacheable(),
+
+  /**
+    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.
+  
+    @param {Number} length the length or null
+    @returns {SC.SparseArray} receiver
+  */
+  provideLength: function(length) {
+    if (SC.none(length)) this._sa_content = null ;
+    if (length !== this._length) {
+      this._length = length ;
+      if (this._requestingLength <= 0) this.enumerableContentDidChange() ;
+    }
+    return this ;
+  },
+
+  // ..........................................................
+  // READING CONTENT 
+  // 
+
+  /** 
+    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.
+    
+    @property {Number}
+  */
+  rangeWindowSize: 1,
+  
+  /** 
+    Returns the object at the specified index.  If the value for the index
+    is currently undefined, invokes the didRequestIndex() method to notify
+    the delegate.
+    
+    @param  {Number} idx the index to get
+    @return {Object} the object
+  */
+  objectAt: function(idx) {
+    var content = this._sa_content, ret ;
+    if (!content) content = this._sa_content = [] ;
+    if ((ret = content[idx]) === undefined) {
+      this.requestIndex(idx);
+      ret = content[idx]; // just in case the delegate provided immediately
+    }
+    return ret ;
+  },
+
+  _TMP_RANGE: {},
+  
+  /**
+    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.
+    
+    @param {SC.SparseArray} receiver
+  */
+  requestIndex: function(idx) {
+    var del = this.delegate;
+    if (!del) return this; // nothing to do
+    
+    // adjust window
+    var len = this.get('rangeWindowSize'), start = idx;
+    if (len > 1) start = Math.floor(start / windowSize);
+    if (len < 1) len = 1 ;
+    
+    // invoke appropriate callback
+    this._requestingIndex++;
+    if (del.sparseArrayDidRequestRange) {
+      var range = this._TMP_RANGE;
+      range.start = start;
+      range.length = len;
+      del.sparseArrayDidRequestRange(this, range);
+      
+    } else if (del.sparseArrayDidRequestIndex) {
+      while(--len >= 0) del.sparseArrayDidRequestIndex(this, start + len);
+    }
+    this._requestingIndex--;
+
+    return this ;
+  },
+  
+  /**
+    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().
+    
+    @param {Range} range the range to apply to
+    @param {Array} array the array of objects to insert
+    @returns {SC.SparseArray} reciever
+  */
+  provideObjectsInRange: function(range, array) {
+    var content = this._sa_content ;
+    if (!content) content = this._sa_content = [] ;
+    var start = range.start, len = range.length;
+    while(--len >= 0) content[start+len] = array[len];
+    if (this._requestingIndex <= 0) this.enumerableContentDidChange() ;
+    return this ;
+  },
+
+  _TMP_PROVIDE_ARRAY: [],
+  _TMP_PROVIDE_RANGE: { length: 1 },
+  
+  /**
+    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.
+    
+    @param {Number} index the index to insert
+    @param {Object} the object to insert
+    @return {SC.SparseArray} receiver
+  */
+  provideObjectAtIndex: function(index, object) {
+    var array = this._TMP_PROVIDE_ARRAY, range = this._TMP_PROVIDE_RANGE;
+    array[0] = object;
+    range.start = index;
+    return this.provideObjectsInRange(range, array);
+  },
+
+  /**
+    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.
+    
+    @param {Range} the range
+    @returns {SC.SparseArray} receiver
+  */
+  objectsDidChangeInRange: function(range) {
+
+    // delete cached content
+    var content = this._sa_content ;
+    if (content) {
+      // if range covers entire length of cached content, just reset array
+      if (range.start === 0 && SC.maxRange(range)>=content.length) {
+        this._sa_content = null ;
+        
+      // otherwise, step through the changed parts and delete them.
+      } else {
+        var start = range.start, loc = Math.min(start + range.length, content.length);
+        while (--loc>=start) content[loc] = undefined;
+      }
+    }    
+    this.enumerableContentDidChange(range) ; // notify
+    return this ;
+  },
+  
+  /**
+    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.
+    
+    @param {Object} obj the object to search for
+    @returns {Number} the discovered index or -1 if not found
+  */
+  indexOf: function(obj) {
+    var del = this.delegate ;
+    if (del && del.sparseArrayDidRequestIndexOf) {
+      return del.sparseArrayDidRequestIndexOf(this, obj);
+    } else {
+      var content = this._sa_content ;
+      if (!content) content = this._sa_content = [] ;
+      return content.indexOf(obj) ;
+    }
+  },  
+  
+  // ..........................................................
+  // EDITING
+  // 
+
+  /**
+    Array primitive edits the objects at the specified index unless the 
+    delegate rejects the change.
+    
+    @param {Number} idx the index to begin to replace
+    @param {Number} amt the number of items to replace
+    @param {Array} objects the new objects to set instead
+    @returns {SC.SparseArray} receiver
+  */
+  replace: function(idx, amt, objects) {
+    objects = objects || [] ;
+
+    // if we have a delegate, get permission to make the replacement.
+    var del = this.delegate ;
+    if (del) {
+      if (!del.sparseArrayShouldReplace || 
+          !del.sparseArrayShouldReplace(this, idx, amt, objects)) {
+            return this;
+      }
+    }
+
+    // go ahead and apply to local content.
+    var content = this._sa_content ;
+    if (!content) content = this._sa_content = [] ;
+    content.replace(idx, amt, objects) ;
+    
+    // update length
+    var len = objects ? (objects.get ? objects.get('length') : objects.length) : 0;
+    var delta = len - amt ;
+    if (!SC.none(this._length)) {
+      this.propertyWillChange('length');
+      this._length += delta;
+      this.propertyDidChange('length');
+    }
+
+    this.enumerableContentDidChange(idx, amt, delta) ;
+    return this ;
+  },
+
+  /** 
+    Resets the SparseArray, causing it to reload its content from the 
+    delegate again.
+  */
+  reset: function() {
+    this._sa_content = null ;
+    this._length = null ;
+    this.enumerableContentDidChange() ;
+    this.invokeDelegateMethod(this.delegate, 'sparseArrayDidReset', this);
+    return this ;
+  }
+      
+}) ;
+
+SC.SparseArray.array = function(len) {
+  return this.create({ _length: len||0 });
+};