map()
Create a new API instance with the result set defined by the values returned from the callback function.
Description
The map()
method is useful for traversing a result set and creating a new instance, whose result set is defined by the values returned. As such any logic condition can be applied to the values of the original result set, transforming the data as required.
This method makes use of the fact that DataTables API objects are "array like", in that they inherit a lot of the abilities and methods of the Javascript Array
type.
Important compatibility note: This method is implemented in the same way as the ECMA-262 5th edition Array.prototype.map
method and is not identical to jQuery's $.map
method. The key difference is in how the returned value is handled. The ECMAScript standard requires that the resulting array (DataTables API instance in this case) is of identical length as the input array, while that is not true in $.map
. When using jQuery's $.map
method null
or undefined
can be returned to remove an item from the resulting array. In ECMAScript, and this DataTables method, those values are used in the new instance.
If you wish to remove items from the result set, use the filter()
method.
This method is a proxy for the Javascript Array.prototype.map
method and is provided as a utility method for the DataTables API. For more information about the original method, please refer to the Mozilla MDN documentation for map
. In browsers which do not support map
natively, a polyfill is provided to allow this DataTables method to operate as expected.
Type
function map( fn )
- Description:
Iterate over the result set of an API instance, creating a new API instance from the values returned by the callback.
- Parameters:
Name Type Optional 1 fn
No Callback function which is called for each item in the API instance result set. The callback is called with three parameters:
- The element value
- The element index in the result set
- The API instance being traversed
The value returned by the callback will be added to the new API instance's result set, or
undefined
if no value is returned.- Returns:
New API instance with the values in the result set as those returned by the callback.
Example
Square the values from a column:
var table = new DataTable('#myTable');
var squared = table
.column(0)
.data()
.map(function (value, index) {
return value * value;
});