dojo/_base/array

Summary

The Javascript v1.6 array extensions.

See the dojo/_base/array reference documentation for more information.

Methods

clearCache()

Defined by dojo/_base/array

every(arr,callback,thisObject)

Defined by dojo/_base/array

Determines whether or not every item in arr satisfies the condition implemented by callback.

This function corresponds to the JavaScript 1.6 Array.every() method, with one difference: when run over sparse arrays, this implementation passes the "holes" in the sparse array to the callback function with a value of undefined. JavaScript 1.6's every skips the holes in the sparse array. For more details, see: https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Objects/Array/every

Parameter	Type	Description
arr	Array | String	the array to iterate on. If a string, operates on individual characters.
callback	Function | String	a function is invoked with three arguments: item, index, and array and returns true if the condition is met.
thisObject	Object	Optional may be used to scope the call to callback

Returns: Boolean

Examples

Example 1

// returns false
array.every([1, 2, 3, 4], function(item){ return item>1; });

Example 2

// returns true
array.every([1, 2, 3, 4], function(item){ return item>0; });

filter(arr,callback,thisObject)

Defined by dojo/_base/array

Returns a new Array with those items from arr that match the condition implemented by callback.

This function corresponds to the JavaScript 1.6 Array.filter() method, with one difference: when run over sparse arrays, this implementation passes the "holes" in the sparse array to the callback function with a value of undefined. JavaScript 1.6's filter skips the holes in the sparse array. For more details, see: https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Objects/Array/filter

Parameter	Type	Description
arr	Array	the array to iterate over.
callback	Function | String	a function that is invoked with three arguments (item, index, array). The return of this function is expected to be a boolean which determines whether the passed-in item will be included in the returned array.
thisObject	Object	Optional may be used to scope the call to callback

Returns: Array

Examples

Example 1

// returns [2, 3, 4]
array.filter([1, 2, 3, 4], function(item){ return item>1; });

forEach(arr,callback,thisObject)

Defined by dojo/_base/array

for every item in arr, callback is invoked. Return values are ignored. If you want to break out of the loop, consider using array.every() or array.some(). forEach does not allow breaking out of the loop over the items in arr.

This function corresponds to the JavaScript 1.6 Array.forEach() method, with one difference: when run over sparse arrays, this implementation passes the "holes" in the sparse array to the callback function with a value of undefined. JavaScript 1.6's forEach skips the holes in the sparse array. For more details, see: https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Objects/Array/forEach

Parameter	Type	Description
arr	Array | String
callback	Function | String
thisObject	Object	Optional

Examples

Example 1

// log out all members of the array:
array.forEach(
      [ "thinger", "blah", "howdy", 10 ],
      function(item){
          console.log(item);
      }
);

Example 2

// log out the members and their indexes
array.forEach(
      [ "thinger", "blah", "howdy", 10 ],
      function(item, idx, arr){
          console.log(item, "at index:", idx);
      }
);

Example 3

// use a scoped object member as the callback

var obj = {
      prefix: "logged via obj.callback:",
      callback: function(item){
          console.log(this.prefix, item);
      }
};

// specifying the scope function executes the callback in that scope
array.forEach(
      [ "thinger", "blah", "howdy", 10 ],
      obj.callback,
      obj
);

// alternately, we can accomplish the same thing with lang.hitch()
array.forEach(
      [ "thinger", "blah", "howdy", 10 ],
      lang.hitch(obj, "callback")
);

indexOf(arr,value,fromIndex,findLast)

Defined by dojo/_base/array

locates the first index of the provided value in the passed array. If the value is not found, -1 is returned.

This method corresponds to the JavaScript 1.6 Array.indexOf method, with two differences:

1. when run over sparse arrays, the Dojo function invokes the callback for every index whereas JavaScript 1.6's indexOf skips the holes in the sparse array.
2. uses equality (==) rather than strict equality (===)

For details on this method, see: https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Objects/Array/indexOf

Parameter	Type	Description
arr	Array
value	Object
fromIndex	Integer	Optional
findLast	Boolean	Optional Makes indexOf() work like lastIndexOf(). Used internally; not meant for external usage.

Returns: Number

lastIndexOf(arr,value,fromIndex)

Defined by dojo/_base/array

locates the last index of the provided value in the passed array. If the value is not found, -1 is returned.

This method corresponds to the JavaScript 1.6 Array.lastIndexOf method, with two differences:

1. when run over sparse arrays, the Dojo function invokes the callback for every index whereas JavaScript 1.6's lasIndexOf skips the holes in the sparse array.
2. uses equality (==) rather than strict equality (===)

For details on this method, see: https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Objects/Array/lastIndexOf

Parameter	Type	Description
arr	undefined
value	undefined
fromIndex	Integer	Optional

Returns: Number

map(arr,callback,thisObject,Ctr)

Defined by dojo/_base/array

applies callback to each element of arr and returns an Array with the results

This function corresponds to the JavaScript 1.6 Array.map() method, with one difference: when run over sparse arrays, this implementation passes the "holes" in the sparse array to the callback function with a value of undefined. JavaScript 1.6's map skips the holes in the sparse array. For more details, see: https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Objects/Array/map

Parameter	Type	Description
arr	Array | String	the array to iterate on. If a string, operates on individual characters.
callback	Function | String	a function is invoked with three arguments, (item, index, array), and returns a value
thisObject	Object	Optional may be used to scope the call to callback
Ctr	undefined

Returns: Array | instance

Examples

Example 1

// returns [2, 3, 4, 5]
array.map([1, 2, 3, 4], function(item){ return item+1 });

some(arr,callback,thisObject)

Defined by dojo/_base/array

Determines whether or not any item in arr satisfies the condition implemented by callback.

This function corresponds to the JavaScript 1.6 Array.some() method, with one difference: when run over sparse arrays, this implementation passes the "holes" in the sparse array to the callback function with a value of undefined. JavaScript 1.6's some skips the holes in the sparse array. For more details, see: https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Objects/Array/some

Parameter	Type	Description
arr	Array | String	the array to iterate over. If a string, operates on individual characters.
callback	Function | String	a function is invoked with three arguments: item, index, and array and returns true if the condition is met.
thisObject	Object	Optional may be used to scope the call to callback

Returns: Boolean

Examples

Example 1

// is true
array.some([1, 2, 3, 4], function(item){ return item>1; });

Example 2

// is false
array.some([1, 2, 3, 4], function(item){ return item<1; });