map()

Since: DataTables 1.10

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

	Name	Type	Optional
1	`fn`	`function`	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.

fn

function

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:

DataTables.Api

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;
	});