IteratorFilter

IteratorFilter Class Sub-package

This mini-package provides a simple class, IteratorFilter, that provides a simple means of selecting certain of a container's members while traversing (iterating through) the container.

This package may be obtained from the following sources:

• The ZOOM reference copy is located on the Fermilab fnalu Unix cluster (for example, on fsgi02.fnal.gov), in directories rooted at /afs/fnal.gov/files/reports/working-groups/fpcltf/ZMtools.
• For CDF or D0 users, a reference copy is maintained in the standard CDF or D0 manner on their respective Unix systems.
• The package is kept in a CVS repository managed by SoftRelTools, and may be checked out directly from cvsuser@zoomcvs.fnal.gov:/usr/people/cvsuser/repository.

Description

User Interface

Implementation

Walter Brown, Module Coordinator
Fermilab Physics Class Library Task Force

Comments, questions about getting started, feature needs, and bug/annoyance reports may be sent to zoom-support@fnal.gov or zoom@fnal.gov.

Description

This module provides a class designed to simplify a common idiom, traversing a container, selecting ("filtering" )from the container only those members of current interest. This idiom is typically expressed as follows:

    // Container-related information:
    typedef /* ... */                  Container;
    typedef Container::const_iterator  Iter;
    typedef Container::const_reference Ref;
    Container  c;

    // Filtering information:
    extern  bool  meetsCriteria( Ref );

    // Traversal:
    for ( Iter  i( c.begin() ); i != c.end(); ++i )  {
      if ( meetsCriteria(*i) )  {
        // ... process *i as desired ...
      }
    }
    

User Interface

To use the IteratorFilter facilities, a user first includes the header file:

    #include "ZMtools/IteratorFilter.h"
    

Subsequently, the user may instantiate and employ one or more IteratorFilters, as in the following simple example:

    // Specify container information:
    int const  NA( 20 );
    typedef    std::vector<int>   A;
    typedef    A::const_iterator  It;

    // Specify filter function information:
    typedef  bool (*FilterFctn) ( int );
    bool odd( int i )  { return i % 2; }

    // Specify IteratorFilter (IF) information:
    typedef IteratorFilter<It,FilterFctn>  Phil;

    // Prepare the container:
    A   a(NA);
    It  end( a.end() );

    // Initialize container:
    // ...

    // Prepare IteratorFilter:
    Phil  p = Phil(end, &odd);

    // Filter the container's contents:
    for ( It  i( a.begin() );  p(i);  ++i )
      std::cout << *i << ' ';
    std::cout << std::endl;
    

The actual use of the IteratorFilter<> object is confined to the predicate of the for loop, (here, p(i)). The filter (1) adjusts (by side effect) its iterator parameter so as to refer to the next container element (if any) that meets the selection criteria embedded in the filter function. The result of the filter is a boolean whose truth value indicates the success of the filtering operation.

Test programs that validate the behavior of the IteratorFilter<> template is available in the programs zmtIFtest1.cc, zmtIFtest2.cc, and zmtIFtest3.cc, all furnished as part of this module. The above example is abstracted from zmtIFtest2.cc.

Implementation

The sole header file needed by the user is ZMtools/IteratorFilter.h. This file contains the complete implementation in the form of a template class, IteratorFilter<>, together with a specialization of this template that handles the case of a zero-sized container.