list.js

javascript 很酷的类库

/*
 * Isomorphic SmartClient
 * Version 6.5 (2008-04-30)
 * Copyright(c) 1998-2007 Isomorphic Software, Inc. All rights reserved.
 * "SmartClient" is a trademark of Isomorphic Software, Inc.
 *
 * [e-mail]
 *
 * http://smartclient.com/license
 */

 



//> @interface List
// An interface for an ordered collection of items.
// <P>
// This is the interface that is expected by list-oriented display components such as the
// ListGrid.  The JavaScript native Array object is retrofitted to support the List interface.
// Also, a valid List can be created by mixing the List interface into any class that supports:
// <ul>
// <li> for read-only support: get(position), getLength()
// <li> for modifiable support: set(position), addAt(object, position), removeAt(position)
// </ul>
// <P>
// NOTE: this interface is compatible with the java.util.List interface, except that:
// <ul>
// <li> for removal by index, removeAt() must be called instead of remove().  In Java, remove()
// is an overloaded method that takes either an int or Object, whereas in JavaScript, a
// Number is an Object.
// <li> Iterators don't exist.
// </ul> 
// Some methods from the Java List interface have been omitted from the documentation to avoid
// redundancy.
//
// @treeLocation Client Reference/System
// @visibility external
//<
isc.ClassFactory.defineInterface("List");

// Read-only
// --------------------------------------------------------------------------------------------
// - basics that must be implemented
//   "get", "getLength",
//
// - routines that can be implemented in terms of basics
//   - trivial routines
//     "isEmpty", "itemIsPresent", "rangeIsPresent", "first", "last", 
//   - routines to consider for a custom implementation for performance
//     "indexOf", "lastIndexOf", "contains", "containsAll", "intersect", 
//     "getItems", "getRange", "duplicate", 

// Modification
// --------------------------------------------------------------------------------------------
// - basics that must be implemented
//   "set", "addAt", "removeAt",
//   - NOTE: technically, set() and setLength() are sufficient as a minimal interface, however,
//     this means that addAt() and removeAt() would need to be implemented by
//     lengthening/shortening the List and then setting every slot beyond the modified point,
//     which seems like a very silly default implementation.

// - routines that can be implemented in terms of basics
//   - trivial routines
//     "add", "addList",
//   - routines to consider for a custom implementation for performance
//      "setLength", "addListAt", "remove", "removeList", "sort", "sortByProperty"

//   - notifications
//     "dataChanged", "_startChangingData", "_doneChangingData", 




isc.List.addInterfaceMethods({

init : function () {
	if (!this.data) this.data = [];
},

// --------------------------------------------------------------------------------------------
// Read-only Interface
// --------------------------------------------------------------------------------------------

// Basics that must be implemented
// --------------------------------------------------------------------------------------------

//>	@method		list.get()
// Return the item at a particular position
// @group access
//
//		@param	pos	(Number)	position of the element to get
//
//		@return	(object)		whatever's at that position, undef if not found	
// @visibility external
//<
// expected to be implemented by target

//>	@method		list.getLength()
// Return the number of items in this list
//
// @group access
//
//		@return	(Number)	number of items in the list
// @visibility external
//<
// expected to be implemented by target

// Implementable in terms of basics
// --------------------------------------------------------------------------------------------

//>	@method		list.isEmpty()
// Return whether or not this array is empty
//
// @group access
//		@return	(boolean)	true == this array is empty, false == some items in the array	
// @visibility external
//<
// [stolen from Array]

//>	@method		list.first()
// Return the first item in this list
//
// @group access
//		@return	(any)	first item in the list
// @visibility external
//<
first : function () {
	return this.get(0);
},

//>	@method		list.last()
// Return the last item in this list
//
// @group access
//		@return	(any)	last item in the list
// @visibility external
//<
last : function () {
	return this.get(this.getLength()-1);
},

// Below might need custom implementations for performance
// --------------------------------------------------------------------------------------------

//>	@method		list.indexOf()
// Return the position in the list of the first instance of the specified object.
// <p>
// If pos is specified, starts looking after that position.
// <p>
// Returns -1 if not found.
//
// @group access
//		@param	obj		 (any)		object to look for
//		@param	[pos]	 (number)	earliest index to consider
//		@param	[endPos] (number)	last index to consider
//
//		@return	(number)			position of the item, if found, -1 if not found	
// @visibility external
//<
indexOf : function (obj, pos, endPos) {
	// normalize position to the start of the list
	if (pos == null) pos = 0;
    if (endPos == null) endPos = this.getLength() - 1;
	
	for (var i = pos; i <= endPos; i++) {
		if (this.get(i) == obj) return i;
	}

	// not found -- return the not found flag
	return -1;
}, 

//>	@method		list.lastIndexOf()
// Return the position in the list of the last instance of the specified object.
// <p>
// If pos is specified, starts looking before that position.
// <p>
// Returns -1 if not found.
//
// @param	obj		(any)		object to look for
// @param	[pos]	 (number)	last index to consider
// @param	[endPos] (number)	earliest index to consider
//
// @return	(number)			position of the item, if found, -1 if not found	
//
// @group access
// @visibility external
//<
lastIndexOf : function (obj, pos, endPos) {
	// normalize position to the end of the list
	if (pos == null) pos = this.getLength() - 1;
    if (endPos == null) endPos = 0;
	
	for (var i = pos; i >= endPos; i--)
		if (this.get(i) == obj) return i;

	// not found -- return the not found flag
    return -1;
},

//>	@method		list.findIndex()
// Find the index of the first Object where property == value in the object.
// <P>
// Pass an Object instead to match multiple properties.
// <P>
// Note: for string values, matches are case sensitive.
//
// @param propertyName (String or Object) property to match, or if an Object is passed, set of
//                                        properties and values to match
// @param [value] (any) value to compare against (if propertyName is a string)
// @return (int) index of the first matching Object or -1 if not found
//
// @group access, find
// @visibility external
//<
// [stolen from Array]

//>	@method		list.findNextIndex()
// Like +link{findIndex()}, but inspects a range from startIndex to endIndex.
//
// @param startIndex (int) first index to consider
// @param propertyName (String or Object) property to match, or if an Object is passed, set of
//                                        properties and values to match
// @param [value] (any) value to compare against (if propertyName is a string)
// @param [endIndex] (int) last index to consider
// @return (int) index of the first matching Object or -1 if not found
//
// @group access, find
// @visibility external
//<

findNextIndex : function (start, property, value, endPos) {
    var length = this.getLength();    

    if (start == null) start = 0;
    else if (start >= length) return -1;
    if (endPos == null) endPos = length - 1;
    if (property == null) return -1;

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

//>	@method list.find()
// Like +link{findIndex()}, but returns the object itself instead of its index.
//
// @param propertyName (String or Object) property to match, or if an Object is passed, set of
//                                        properties and values to match
// @param [value] (any) value to compare against (if propertyName is a string)
// @return (Object) first matching object or null if not found	
//
// @group access, find
// @visibility external
//<
// [stolen from Array]

//>	@method list.findAll()
// Find all objects where property == value in the object.
// <P>
// Pass an Object as the <code>propertyName</code> argument to match multiple properties.
//
// @param propertyName (String or Object) property to match, or if an Object is passed, set of
//                                        properties and values to match
// @param [value] (any) value to compare against (if propertyName is a string)
// @return (Array) all matching Objects or null if none found	
//
// @group access, find
// @visibility external
//<
findAll : function (property, value) {

    if (property == null) return null;

	if (isc.isA.String(property)) {
        var matches = null,
            l = this.getLength()
        ;
        // single property to match
        for (var i = 0; i < l; i++) {
            var item = this.get(i);
			if (item && item[property] == value) {
                if (matches == null) matches = [];
                matches.add(item);
            }
		}
        return matches;
	} else {
        // "property" is an object specifying a set of properties to match
        return this.findAllMatches(property);
	}
},

//>	@method		list.contains()
// Return if this list contains the specified object.
// <P>
// If pos is specified, starts looking after that position.
//
// @group access
//		@param	obj		(any)		item to look for
//		@param	[pos]	(number)	optional position in the list to look after
//	
//		@return	(boolean)	true == item was found, false == not found
// @visibility external
//<
// [stolen from Array]

//> @method     list.containsAll()
// Return whether this list contains all the item in the specified list.
//
// @group access
//      @param list     (List)      items to look for
//      @return (boolean)   whether all items were found
// @visibility external
//<
// [stolen from Array]

//>	@method		list.intersect()
// Return the list of items that are in both this list and the passed-in list(s).
//
//		@group	arrayMath
//
//		@param	lists    (all List arguments)		lists to intersect with
//		@return	(List)	intersection
// @visibility external
//<
// [stolen from Array]

//> @method     list.equals()
// Return whether this list is equal to another list.
// <P>
// Two lists are equal only if they have the same length and all contained items are in the same
// order and are also equal.
//
// @group access
//      @param list     (List)      list to check for equality
//      @return (boolean)   whether the specified list is equal to this list
// @visibility external
//<
// [stolen from Array]

//>	@method		list.getItems()
// Return the items at a list of specified positions.
//
// @group access
//		@param	itemList	(List of Number)		array of positions
//
//		@return	(array)		subset of the array, in the same order as itemList
// @visibility external
//<
// [stolen from Array]

//>	@method		list.getRange()
// Return the items between position start and end, non-inclusive at the end.
//
// @group access
//		@param	start	(number)	start position
//		@param	end		(number)	end position
//
//		@return	(Array)		subset of the array from start -> end-1
// @visibility external
//<
getRange : function (start, end) {
    if (end == null) end = this.getLength() - 1;
    var output = [];
    for (var i = start; i < end; i++) {
        output[output.length] = this.get(i);
    }
	return output;
},

//>	@method		list.duplicate()	(A)
// Return an Array that is a shallow copy of the list, that is, containing the same items.
//
// @group access
//		@return	(Array)		new array, pointing to the same items	
// @visibility external