array.js

javascript 很酷的类库

    for (var i = this.length - 1, l = list.length; i >= pos; i--) {
        this[i+l] = this[i];
    }
    
    // add the new items in list
    for (i = 0; i < l; i++) {
        this[i+pos] = list[i];
    }
    
	// call dataChanged in case anyone is observing it
	this.dataChanged();

    // return the list that was added
    return list;
}, 


//>	@method		array.remove()
// @include list.remove()
//<
remove : function (obj) {
    

    var index = this.indexOf(obj);
    if (index == -1) return false;

	for (var i = index; i < this.length; i++) this[i] = this[i+1];
    this.length = this.length-1;

    this.dataChanged();
    
    return true; // indicating object was removed, per java.util.Collection
},

//>	@method		array.removeList()
// @include list.removeList()
//<
removeList : function (list) {
    if (list == null) return null;

	// run through all the items, putting things we want to retain into new list output
	for (var output = [], i = 0, l = this.length;i < l;i++) {
		if (!list.contains(this[i])) output.add(this[i]);
    }
	// now set the items in this list to the items in output
	this.setArray(output);

	// return the list that was removed
	return list;
}, 

// useful in chaining expressions eg someList.removeEvery(null).getProperty(...)
// .. removeList/removeAll don't work in this circumstance
removeEvery : function (value) {
    this.removeList([value]);
    return this;
},

//>	@method		array.dataChanged()	(A)
// @include list.dataChanged()
//<
dataChanged : function () {},

// methods to ensure dataChanged() fired only once when a series of changes are made: see List.js
_startChangingData : function () {
    var undef;
	if (this._dataChangeFlag === undef) this._dataChangeFlag = 0;
	this._dataChangeFlag++;
},

_doneChangingData : function () {
	if (--this._dataChangeFlag == 0) this.dataChanged();
},

// In some cases we want to perform a one-liner - call dataChanged unless we're inside a data
// changing loop
_isChangingData : function () {
    return (this._dataChangeFlag != null && this._dataChangeFlag > 0); 
}

// End of List API
// --------------------------------------------------------------------------------------------

//>	@method		array.setArray()
// Completely change the contents of one array to the contents of another array.
// <P>
// This is useful if you have an external pointer to an array, but you want to change its
// contents, such as when you remove some items from the array.
//
//		@group	dataChanged
//
//		@param	(array)		array to set this array to
//<
setArray : function (list) {
	// match length
	this.setLength(list.length);

	// fill slots
	for (var i = 0; i < list.length; i++) this[i] = list[i];
	
	// call dataChanged in case someone is observing data in the list
	this.dataChanged();
},

//>	@method		array.addAsList()
// Add either a single object or a list of items to this array.
//
//		@group	dataChanged
//
//		@param	list	(array or object)		a single object or a list of items to add
//
//		@return	(list)				list of items that were added
//<
addAsList : function (list) {
	if (!isc.isAn.Array(list)) list = [list];
	// return the objects that were added
	return this.addList(list);
},

//>	@method		array.removeRange()
// Remove and return a range of elements from an array - same return value as array.slice(),
// but removes the slice from the array
//
//		@group	dataChanged
//
//		@param	startPos	(number)	start position of range to remove
//      @param  endPos      (number)    end position of range to remove
//
//      @return (array) array of items that were removed
//<
removeRange : function (startPos, endPos) {
    // fall through to splice
    var undefined;
    if (startPos === undefined) return this;    // no arguments
    if (!isc.isA.Number(startPos)) startPos = 0;
    if (!isc.isA.Number(endPos)) endPos = this.length;
    return this.splice(startPos, endPos - startPos);
}, 

//>	@method		array.removeWhere()
//			Remove all instances of object from this array
//		@group	dataChanged
//
//		@param	property	(string)	property to look for
//		@param	value		(string)	value to look for
//
//		@return	(array)		list of items that were removed	
//<
removeWhere : function (property, value) {
	for (var i = 0, newList = []; i < this.length; i++) {
		if (!this[i] || this[i][property] != value) {
			newList.add(this[i]);
		}
	}
	this.setArray(newList);
}, 

//>	@method		array.removeEmpty()
//			Remove all empty slots in this array (where array[n] == null)
//		@group	dataChanged
//<
removeEmpty : function (property, value) {
	for (var i = 0, newList = []; i < this.length; i++) {
		if (this[i] != null) {
			newList.add(this[i]);
		}
	}
	this.setArray(newList);
}, 

//>	@method		array.getProperty()
// Return a new array where the value of item i is the value of "property" of item i in this
// array.  If an item doesn't have that property or is null, return item will be null.
//
//		@group	iteration
//		@param	property	(string)	name of the property to look for
//
//		@return	(array)		array of the values of property in each item of this list	
// @visibility external
//<
getProperty : function (property) {
	for(var output = [], i = 0, l = this.length;i < l;i++)
		output[output.length] = (this[i] ? this[i][property] : null);
	return output;
}, 

//>@method array.getValueMap()
// @include list.getValueMap()
// @visibility external
//<
getValueMap : function (idField, displayField) {
    var valueMap = {};
    for (var i = 0, l = this.getLength(); i < l; i++) {
        var item = this.get(i);
        // Don't attempt to pull properties from empty values / basic data types in the list.
        if (!isc.isAn.Object(item)) continue;
        if (item && item[idField]) {
            valueMap[item[idField]] = item[displayField];
        }
    }
    return valueMap;
},

//>	@method		array.map()
// Return an array where the value of item <code>i</code> is the result of calling the provided
// function on item <code>i</code> in this array.
// <P>
// The function to call can either be provided directly as a function object, in which case it
// is invoked with the item as the first argument, or can be provided as the String name of a
// method present on each item, which will be invoked.  In the latter case, if any item is null
// or lacks the named method, null will be returned for that item.
// <P>
// Examples:<PRE>
//    // line up widgets at 20 pixels from page edge
//    [widget1, widget2].map("setPageLeft", 20);
//
//    // find furthest right widget
//    [widget1, widget2].map("getPageRight").max();
// </PRE>
// 
//		@group	iteration
//
//		@param	method  (string or function) function object, or name of method
//	    @param	[(arguments 1-N)]	(any)	 arguments to pass to the function or method
//                                           invoked on each item
//		@return	(array)		array of returned values
// @visibility external
//<
map : function (method, arg1, arg2, arg3, arg4, arg5) {
    var isFunc = isc.isA.Function(method),
        output = [],
        length = this.getLength();
	for (var i = 0; i < length; i++) {
        var item = this.get(i);
        if (isFunc) {
            output[i] = method(item, arg1, arg2, arg3, arg4, arg5);
        } else {
            output[i] = (item && item[method] != null ?
                         item[method](arg1, arg2, arg3, arg4, arg5) : null);
        }
    }
    return output;
},

//>	@method		array.setProperty()
//	Set item[property] = value for each item in this array.
//		@group	iteration
//
//		@param	property	(string)	name of the property to set
//		@param	value		(any)		value to set to
// @visibility external
//<
setProperty : function (property, value) {
	for(var i = 0, l = this.length;i < l;i++)
		if (this[i]) this[i][property] = value;
}, 

//>	@method		array.clearProperty()
// Delete property in each item in this array.
//		@group	iteration
//
//		@param	property 	(string)	name of the property to clear
// @visibility external
//<
clearProperty : function (property) {
	for(var i = 0, l = this.length;i < l;i++)
		if (this[i]) delete this[i][property];
}, 

//>	@method		array.getProperties()
// Return a copy of the array where each object has only the list of properties provided.
//		@group	iteration
//
//		@param	properties	(string[])	names of the properties you want to export
//		                    (object)	object with the properties you want to export
//
//		@return	(Array)		new Array with each item limited to the specified properties
//<
getProperties : function (properties) {
    return isc.applyMask(this, properties);
},

//>	@method		array.getUniqueItems()
// Return a list of each unique item in this list exactly once.
// <P>
// Returns in the same order they were found in the list.
// <P>
// Usage example:<br>
// &nbsp;&nbsp;&nbsp;&nbsp;uniqueList = myArray.getProperty("foo").getUniqueItems();
//
//		@group	subset
//
//		@return	(array)	list of each unique item in the list
// @visibility external
//<
getUniqueItems : function () {
	for (var output = [], i = 0, l = this.length; i < l; i++) {
		if (!output.contains(this[i])) output[output.length] = this[i];
	}
	return output;
},

//>	@method		array.slice()
// Return a contiguous range of rows of the array.  
// DOES NOT include element at position <code>end</code> (similar to .substring())
// <P>
// NOTE: uses browser's native implementation if one is provided
//
// @param	start	(number)	start index
// @param	[end]	(number)	end index, if not specified will be list.length
//
// @return	(array)	new array with items from start -> end-1 in it	
// @group	subset
//<
slice :
	(Array.prototype.slice 
		? Array.prototype.slice
		: function (start, end) {
			if (end == null) end = this.length;
			for(var output = [], l = this.length; start < end && start < l;start++)
				output[output.length] = this[start];
			return output;
		}
	), 

//>	@method array.findIndex()
// @include list.findIndex
//<
findIndex : function (property, value) {
    return this.findNextIndex(0, property, value);
},

//>	@method array.findNextIndex()
// @include list.findNextIndex
//<
findNextIndex : function (start, property, value, endPos) {
    if (start == null) start = 0;
    else if (start >= this.length) return -1;
    if (endPos == null) endPos = this.length - 1;
    
    if (property == null) return -1;

	if (isc.isA.String(property)) {
        // single property to match
		for (var i = start; i <= endPos; i++) {
			if (this[i] && this[i][property] == value) return i;
        }
        return -1;
	} else {
        // "property" is an object specifying a set of properties to match
        return this.findNextMatch(property, start, endPos);
	}
},

// internal: assumes multiple properties
findNextMatch : function (properties, start, end) {
    var propertyNames = isc.getKeys(properties);
    for (var i = start; i <= end; i++) {
        var item = this.get(i);
        if (!item) continue;
        var found = true;
        for (var j = 0; j < propertyNames.length; j++) {
            var propertyName = propertyNames[j];
            if (item[propertyName] != properties[propertyName]) {
                found = false;
                break;
            }
        }
        if (found) return i;
    }
    return -1;
},

//>	@method array.find()
// @include list.find
//<
find : function (property, value) {
    var index = this.findIndex(property, value);
    return (index != -1) ? this.get(index) : null;
},

// given values for the primary key fields ("record"), find the _index of_ the unique 
// matching record.
// Will automatically trim extra, non-key fields from "record"
findByKeys : function (record, dataSource, pos, endPos) {
    if (record == null) {
        //>DEBUG
        isc.Log.logWarn("findByKeys: passed null record");
        //<DEBUG
        return -1;
    }

    // get the values for all the primary key fields from the passed record
    var findKeys = {}, 
        keyFields = dataSource.getPrimaryKeyFields(),
        hasKeys = false;
    
    for (var keyField in keyFields) {
        hasKeys = true;
        if (record[keyField] == null) {
            //>DEBUG
            isc.Log.logWarn("findByKeys: passed record does not have a value for key field '"
            			 + keyField + "'");
            //<DEBUG