Recipe 21.3 Filtering Recordsets

21.3.1 Problem

You want to create a new recordset that contains a subset of the original.

21.3.2 Solution

Use the RecordSet.filter( ) method.

21.3.3 Discussion

You can manually create a new RecordSet object by reading the records from a recordset and writing selected ones to a new recordset. However, this is unnecessarily laborious. Instead, you should use the filter( ) method, which handles almost all of the processing for you. Simply provide a filter function that contains the logic to decide which records to use. The filter( ) method expects a reference to a filter function as a parameter, and it accepts a second parameter that is automatically passed to the filter function. The second parameter lets you filter records based on different criteria. The filter( ) method returns a new RecordSet object.

filteredRs = rs.filter(filterFunction, context);

The filter function is called once for each record. Each time it is called, it is passed the next record object, and if a context parameter was specified in the filter( ) method call, that value is also passed along to the filter function. Within the filter function you should place the logic to determine whether the record should be included in the filtered recordset. The optional context parameter, if used, lets the filter function filter based on different criteria. If the filter function returns true, then the record is included in the filtered recordset; if it returns false, the record is not included.

function filterFunction (record, context) {
  // Determine whether to include the record and return true or false.
}

Here is an example in which a recordset is filtered twice to create two new recordsets, filteredRs0 and filteredRs1, based on different criteria:

#include "NetServices.as"

// Create and populate a new recordset.
rs = new RecordSet(["ID", "NAME"]);
rs.addItem({ID: 24, NAME: "a"});
rs.addItem({ID: 42, NAME: "b"});
rs.addItem({ID: 66, NAME: "c"});
rs.addItem({ID: 93, NAME: "d"});
rs.addItem({ID: 33, NAME: "e"});

// Define the filter function. 
function filterer (record, context) {

  // If the record's ID value is greater than the context value, return true to
  // include the record. Otherwise, return false and exclude the record.
  if (record.ID > context) {
    return true;
  }
  return false;
}

// Use the filter(  ) method to create two new recordsets. The first one is populated
// with all records in which the ID is greater than 51. The second is populated with
// all records in which the ID is greater than 36.
filteredRs0 = rs.filter(filterer, 51);
filteredRs1 = rs.filter(filterer, 36);

/* Output the values in filteredRs0. Displays:
   record 0
     ID: 66
     NAME: c
   record 1
     ID: 93
     NAME: d
*/
filteredRs0.trace(  );


/* Output the values in filteredRs1. Displays:
   record 0
     ID: 42
     NAME: b
   record 1
     ID: 66
     NAME: c
   record 2
     ID: 93
     NAME: d
*/
filteredRs1.trace(  );

It is not necessary to use the context parameter with the filter( ) method. You can also define a very specific filter function without it:

// Use a filter function that does not require a context parameter. Filter for
// records with ID values between 39 and 72.
function filterer (record) {
  if (record.ID > 39 && record.ID < 72) {
    return true;
  }
  return false;
}

filteredRs = rs.filter(filterer);

/* Output the values from filteredRs:
   record 0
     ID: 42
     NAME: b
   record 1
     ID: 66
     NAME: c
*/
filteredRs.trace(  );

Filtered recordsets contain references to the records of the original recordset. This is important to keep in mind because it means that if you make changes to a record in a filtered recordset, the same change is reflected in the original as well as in any filtered versions of the original.

21.3.4 See Also

See Recipe 6.8 for a discussion of complex datatypes and copying them by reference. To create an independent copy of one or more records in a recordset, copy data manually into a new recordset using the methods of the RecordSet class, as described in Recipe 21.1 and Recipe 21.2.