Microsoft AJAX Library对 Array的扩展 拓荒者

Microsoft AJAX Library 通过向Array添加一些静态方法来扩展Array对象的功能。以下为扩展的方法名和功能的简单对照：

Array.add 函数

将一个元素添加到 Array 对象的末尾。 此函数是静态的，可在不创建对象实例的情况下调用。

/* param
array：要向其添加 item 的数组
item：要添加到数组的对象
*/
Array.add(array, item);

示例代码：

var a = ['a', 'b', 'c', 'd'];
Array.add(a, 'e');
//返回结果: "abcde"
alert(a.toString());

Array.addRange 函数

将指定的 Array 对象的所有元素复制到数组的末尾。 此函数是静态的，可在不创建对象实例的情况下调用。

如果 items 包含的数组不具有任何项，则目标数组保持不变，且不会引发任何异常。

/* param
array：要将 items 添加到其中的数组
items：要追加的项的数组
*/
Array.addRange(array, items);

示例代码：

var a = ['a', 'b', 'c', 'd'];
var b = ['f', 'g','h'];
Array.addRange(a, b);
// 返回结果: "abcdefgh"
alert(a.toString());

Array.clear 函数

从 Array 实例移除所有元素。 此函数是静态的，可在不创建对象实例的情况下调用。

结果数组的 length 属性将为零。

Array.clone 函数

创建 Array 对象的浅表副本。 此函数是静态的，可在不创建对象实例的情况下调用。

使用 clone 函数可以创建 Array 对象的浅表副本。浅表副本仅包含数组元素，无论这些元素是引用类型还是值类型。但是它不包含引用的对象。新 Array 对象中的引用与原始 Array 对象中的引用指向相同的对象。与之相对，Array 对象的深层副本将复制这些元素以及由这些元素直接或间接引用的所有内容。

示例代码：

var a = ['a', 'b', 'c', 'd'];
var b = Array.clone(a);
// View the results: "abcd"
alert(b.toString());

Array.contains 函数

确定指定对象是否是 Array 对象中的元素。 此函数是静态的，可在不创建对象实例的情况下调用。

在 Mozilla Firefox 中，如果数组中的项已设置为 undefined，则调用 item 设置为 undefined 的 contains 函数将返回 true。同样的情况下，在所有其他浏览器中，函数都返回 false。

/* param
array：要搜索的数组
item：要在数组中查找的对象
*/
var itemExists = Array.contains(array, item);

示例代码：

var a = ['red', 'green', 'blue', 'yellow'];
var b = Array.contains(a, "red");
// View the results: "true"
alert(b.toString());

Array.dequeue 函数

从指定的 Array 对象中移除第一个元素，并返回该元素。

使用 dequeue 函数可以从 Array 对象中移除第一个元素。数组中其余元素的索引值都减 1。

/* param
array：要从中移除第一个元素的数组

returns：数组的第一个元素
*/
var firstElement = Array.dequeue(array);

示例代码：

var myArray = [];
var result = "";
Array.add(myArray, 'a');
Array.add(myArray, 'b');
Array.add(myArray, 'c');
Array.add(myArray, 'd');
result = Array.dequeue(myArray);
// View the results: "b,c,d"
alert("Dequeue result: " + result + "myArray: " + myArray.toString());

Array.forEach 函数

对 Array 对象的每个元素调用指定函数。 此函数是静态的，可在不创建对象实例的情况下调用。

method parameter 指定的函数必须以如下所示的顺序接受下列参数：element、index 和 array。 element 参数是数组元素，函数将对其进行操作。 index 参数是 element 的索引，而 array 参数是包含 element 的数组。

注意：在所有浏览器（Mozilla Firefox 除外）中，forEach 函数都忽略数组中值为 undefined 的元素。在所有浏览器中，该函数都忽略未赋值的元素。

/* param
array：要枚举的 Array 对象
method：要对数组中每个元素调用的函数
instance：调用 method 的上下文
*/
Array.forEach(array, method, instance);

示例代码：

var a = ['a', 'b', 'c', 'd'];
a[5] = 'e';
var result = '';

function appendToString(element, index, array) {
    // "this" is the context parameter, i.e. '|'.
    result += element + this + index + ',';
}
Array.forEach(a, appendToString, '|');
// View the results: a|0,b|1,c|2,d|3,e|5,
alert(result);

Array.indexOf 函数

搜索 Array 对象的指定元素并返回该元素的索引。 此函数是静态的，可在不创建对象实例的情况下调用。

/* param
array：要搜索的数组
item：要在数组中查找的对象
startIndex：（可选）指定在数组中搜索的起始元素的索引号

return：如果找到 item，则返回表示该元素在数组中的索引位置的编号；否则返回 -1。
在 Mozilla Firefox 中，如果调用 indexOf 时未设置 item 或将其设置为 undefined，则返回值为 undefined 的第一项的索引。
在同样的情况下，所有其他浏览器都返回 -1。
*/
var indexVar = Array.indexOf(array, item, start);

示例代码：

var a = ['red', 'blue', 'green', 'blue'];
var myFirstIndex = Array.indexOf(a, "blue");
// View the results: "1"
alert("myFirstIndex: " + myFirstIndex);
var mySecondIndex = Array.indexOf(a, "blue", (myFirstIndex + 1) );
// View the results: "3"
alert("mySecondIndex: " + mySecondIndex);

Array.insert 函数

将单个项插入 Array 对象中的指定索引处。 此函数是静态的，可在不创建对象实例的情况下调用。

/* param
array：要将 item 插入到的数组
index：应插入 item 的索引位置
item：要添加到数组的对象

使用 insert 函数可将项插入到 Array 对象的指定索引处。大于 index 的项索引值增加 1。
调用 insert 函数并传递负值的 index 将从数组末尾往回计数。浮点值向下舍入为整数值。
*/
Array.insert(array, index, item);

示例代码：

var a = ['a', 'b', 'd', 'e'];
Array.insert(a, 2, 'c');
// View the results: "a,b,c,d,e"
alert(a);

Array.parse 函数

从字符串表示形式创建数组。 此函数是静态的，可在不创建对象实例的情况下调用。

/* param
value：要转换为数组的字符串

return：通过拆分输入字符串得到的数组；或者，如果未提供 value，则为空数组。
*/
var a = Array.parse(value);

注意：parse 函数通过拆分 value 中的字符串来填充当前数组。 value 中的字符串的格式必须为 "['item1', 'item2', 'item3']"，并且必须包含引号。

Array.remove 函数

从 Array 对象中移除指定项的第一个匹配项。 此函数是静态的，可在不创建对象实例的情况下调用。

使用 remove 函数可以从数组中移除指定项的第一个匹配项。保留在数组中的项的索引值会减 1。

在 Mozilla Firefox 中，调用 remove 函数并且将 item 设置为 undefined 会从数组中移除第一个具有该值的项。在其他浏览器中，在 item 设置为 undefined 的情况下调用该函数不起任何作用。

/* param
array：要从中移除 item 的数组
item：要从数组中的第一个匹配项处移除的对象

return：如果指定项为数组中的元素并且已移除，则为 true；否则为 false。
*/
var isRemoved = Array.remove(array, item);

示例代码：

var a = ['a', 'b', 'c', 'd', 'e'];
Array.remove(a, 'c');
// View the results: "a,b,d,e"
alert(a);
Array.removeAt(a, 2);
 // View the results: "a,b,e"
alert(a);

Array.removeAt 函数

移除 Array 对象中指定索引位置处的元素。 此函数是静态的，可在不创建对象实例的情况下调用。

使用 removeAt 函数可移除数组中指定索引处的项。大于 index 的项索引值减 1。

如果 index 为负数，则 removeAt 函数从数组末尾往回计数。通过大于数组长度的 index 调用 removeAt 函数将无效。

/* param
array：要从中移除 item 的数组
index：要从数组中移除的元素的索引
*/
Array.removeAt(array, index);

示例代码：

var a = ['a', 'b', 'c', 'd', 'e'];
Array.remove(a, 'c');
// View the results: "a,b,d,e"
alert(a);
Array.removeAt(a, 2);
 // View the results: "a,b,e"
alert(a);