API: rows.add() and row.add() return a rows() (or row()) extended object

with newly added rows

- Looking at fnAddData, and about to replace it, I realised that
  fnAddData returned the indexes of the newly added row while the new
  methods didn't. It makes sense for row.add() to return a row()
  extended object with the newly added rows so row().node() etc can be
  used. Also the indexes are in the inst, so that information is also
  available. Likewise is done for its plural counterpart.

- Did consider creating an `augment` static method for the API, and
  might yet do this, but this is the only place to use it at the moment.
  Possibly it might be useful for plug-ins, but before adding, lets see
  how the new API is used.

media/src/api/api.base.js

@@ -523,7 +523,7 @@ _Api.prototype = /** @lends DataTables.Api */{
 
 
 
- _Api.extend = function ( scope, obj, ext )
+_Api.extend = function ( scope, obj, ext )
 {
 	if ( ! obj instanceof _Api ) {
 		return;
@@ -560,6 +560,39 @@ _Api.prototype = /** @lends DataTables.Api */{
 };
 
 
+// @todo - Is there need for an augment function?
+// _Api.augment = function ( inst, name )
+// {
+// 	// Find src object in the structure from the name
+// 	var parts = name.split('.');
+
+// 	_Api.extend( inst, obj );
+// };
+
+
+//     [
+//       {
+//         name:      'data'                -- string   - Property name
+//         val:       function () {},       -- function - Api method (or undefined if just an object
+//         methodExt: [ ... ],              -- array    - Array of Api object definitions to extend the method result
+//         propExt:   [ ... ]               -- array    - Array of Api object definitions to extend the property
+//       },
+//       {
+//         name:     'row'
+//         val:       {},
+//         methodExt: [ ... ],
+//         propExt:   [
+//           {
+//             name:      'data'
+//             val:       function () {},
+//             methodExt: [ ... ],
+//             propExt:   [ ... ]
+//           },
+//           ...
+//         ]
+//       }
+//     ]
+
 _Api.register = function ( name, val )
 {
 	if ( $.isArray( name ) ) {

media/src/api/api.rows.js

@@ -35,7 +35,7 @@ _api.register( 'rows()', function ( selector, opts ) {
 } );
 
 
-_api.registerPlural( 'rows().nodes()', 'row().nodes()' , function () {
+_api.registerPlural( 'rows().nodes()', 'row().node()' , function () {
 	return this.iterator( 'row', function ( settings, row ) {
 		// use pluck order on an array rather - rows gives an array, row gives it individually
 		return settings.aoData[ row ].nTr || undefined;
@@ -95,20 +95,30 @@ _api.registerPlural( 'rows().remove()', 'row().remove()', function () {
 
 
 _api.register( 'rows.add()', function ( rows ) {
-	return this.iterator( 'table', function ( settings ) {
-		var row, i, ien;
+	var newRows = this.iterator( 'table', function ( settings ) {
+			var row, i, ien;
+			var out = [];
 
-		for ( i=0, ien=rows.length ; i<ien ; i++ ) {
-			row = rows[i];
+			for ( i=0, ien=rows.length ; i<ien ; i++ ) {
+				row = rows[i];
 
-			if ( row.nodeName && row.nodeName.toUpperCase() === 'TR' ) {
-				_fnAddTr( settings, row );
+				if ( row.nodeName && row.nodeName.toUpperCase() === 'TR' ) {
+					out.push( _fnAddTr( settings, row ) )[0];
+				}
+				else {
+					out.push( _fnAddData( settings, row ) );
+				}
 			}
-			else {
-				_fnAddData( settings, row );
-			}
-		}
-	} );
+
+			return out;
+		} );
+
+	// Return an Api.rows() extended instance, so rows().nodes() etc can be used
+	var modRows = this.rows( -1 );
+	modRows.pop();
+	modRows.push.apply( modRows, newRows );
+
+	return modRows;
 } );
 
 
@@ -150,14 +160,15 @@ _api.register( 'row.add()', function ( row ) {
 		row = row[0];
 	}
 
-	return this.iterator( 'table', function ( settings ) {
+	var rows = this.iterator( 'table', function ( settings ) {
 		if ( row.nodeName && row.nodeName.toUpperCase() === 'TR' ) {
-			_fnAddTr( settings, row );
-		}
-		else {
-			_fnAddData( settings, row );
+			return _fnAddTr( settings, row )[0];
 		}
+		return _fnAddData( settings, row );
 	} );
+
+	// Return an Api.rows() extended instance, with the newly added row selected
+	return this.row( rows[0] );
 } );
 
 

media/src/core/core.data.js

@@ -73,6 +73,7 @@ function _fnAddData ( oSettings, aDataIn, nTr, anTds )
  * it is not cloned).
  *  @param {object} oSettings dataTables settings object
  *  @param {array|node|jQuery} trs The TR element(s) to add to the table
+ *  @returns {array} Array of indexes for the added rows
  *  @memberof DataTable#oApi
  */
 function _fnAddTr( oSettings, trs )
@@ -84,9 +85,9 @@ function _fnAddTr( oSettings, trs )
 		trs = $(trs);
 	}
 
-	trs.each( function () {
-		row = _fnGetRowData( this );
-		_fnAddData( oSettings, row.data, this, row.cells );
+	return trs.map( function (el) {
+		row = _fnGetRowData( el );
+		return _fnAddData( oSettings, row.data, this, row.cells );
 	} );
 }
 

media/src/core/core.filter.js

@@ -381,7 +381,7 @@ function _fnFilterData ( settings )
 
 				// If it looks like there is an HTML entity in the string,
 				// attempt to decode it so sorting works as expected
-				if ( cellData.indexOf('&') !== -1 ) {
+				if ( cellData.indexOf && cellData.indexOf('&') !== -1 ) {
 					cellData = __filter_div.html( cellData ).text();
 				}
 

media/src/ext/ext.filter.js

@@ -14,8 +14,9 @@ $.extend( DataTable.ext.ofnSearch, {
 	},
 
 	string: function ( data ) {
-		return data
-			.replace( __filter_lines, " " );
+		return data.replace ?
+			data.replace( __filter_lines, " " ) :
+			data;
 	}
 } );