NAME

PTools::SDF::IDX - Allow user-defined indices into PTools::SDF::SDF objects

VERSION

This document describes version 0.15, released October, 2004.

SYNOPSIS

    # Trivial example reads /etc/passwd, indexes on Uid,
    # and prints the user information for c-shell users.

    use PTools::SDF::IDX;

    @pwFields = qw(uname passwd uid gid gecos home shell );
    $pw = new PTools::SDF::IDX("/etc/passwd", undef, undef, @pwFields);

    $idx = $pw->indexInit('uid', 'shell', '=~/csh$/');

    foreach (sort keys %$idx) {
        @idx = ('uid',$_);
        print $pw->index(@idx, 'gecos'), "\n"
    }

DESCRIPTION

This perl library extends the PTools::SDF::SDF class to make it easy to create user defined indices. The SDF class loads a field delimited file into an array of associative arrays.

Until now, the only index into the SDF object was the record number. This meant that repeated serial reads of an SDF object were necessary to match on any other fields. Now any arbitrary field can be used to index the file.

Match criteria can be used when initializing the index to select a subset of the records to be indexed. This means that the value of the field indexed does not necessarily need to be unique for every record in the file. It does mean, however, that the field values must be unique with the selection criteria. Therefore, care may be needed when creating the match criteria.

Constructor

None.

As a subclass of PTools::SDF::SDF this uses the constructor in the parent class. See PTools::SDF::SDF.

Methods

indexInit ( IdxField [, MatchCriteria ] )

The first step is to create a field_value to record_number mapping. The match criteria used here are slightly different from that used by the SDF "new" method. The field names must be separated from the criteria used to select records.

IdxField

Specify the name of a key field within each record.

MatchCriteria

If the values for this field are not unique within the current object are not unique, you must specify one or more MatchCriteria patterns to limit the indexing to a subset of records where the key field will be unique.

As an alternative to this, see the compoundInit method, below.

Examples:

The 'indexInit' method must be called once for each user-defined index before invoking the 'index' method using that index. Create an IDX object as you would any SDF object.

  use PTools::SDF::IDX;
  $sdfObj = new PTools::SDF::IDX( $ProductFile );

This first example simply indexes the SDF object on the 'prodnbr' field of the file specified in the $ProductFile variable.

  $sdfObj->indexInit('prodnbr');

In this next example, 'prodnbr' records are indexed only when the 'type' field does not equal the string "Format".

  $sdfObj->indexInit($fieldname, 'type', 'ne "Format"');

This last example show a somewhat more complex set of matching criteria.

  %matchCriteria = (
            type => '!~ /Format|Display Only/',
         prodnbr => 'lt "99999"',
     MATCH_ORDER => 'type:prodnbr',
                   );
  $sdfObj->indexInit($fieldname, %matchCriteria);

Since the match criteria are stored in an associative array no particular selection order is enforced. To impose an order of priority on a set of criteria, use the MATCH_ORDER key to specify in which order the matching will occur.

compoundInit ( IdxFieldList )

It is possible to create a compound index using two or more fields withn each record.

IdxFieldList: This is a list containing the names of two or more fields in the current PTools::SDF::SDF object.

Example:

    # Determine which type of index to initialize

    $compound = 1;

    $field = ($compound ? 'prodnbr&xyzzy' : 'prodnbr' );

    if ($field =~ /&/) {
        $sdfObj->compoundInit( $field );

    } else {
        $sdfObj->indexInit( $field );
    }

See the last example in the index method, below for the syntax used to access a compund index.

index ( IdxFieldName, IdxFieldValue, FieldName [, Value ] )

Once an index has been initialized, use the index method to access the records.

IdxFieldName: The name of the field used to initialize the index.
IdxFieldValue: The search value for the indexed field.
FieldName: The other field name within the record that will be accessed.
Value: The Value is an optional parameter that is used to set the value of the specified FieldName. Without a this parameter, the current value of the field is returned.

Examples:

    $otherFieldValue = $sdfObj->index('prodnbr',$prodNbrValue, 'otherfield');

Think of the (IdxFieldName,IdxFieldValue) combination as an index or 'record number' that is passed to the PTools::SDF::SDF param method. It may be easier to think of this if you build a compound record index as shown in this next example.

    @idx = ('prodnbr',$prodNbrValue);

    $fieldValue = $sdfObj->index( @idx, 'otherfield' );

    $sdfObj->index( @idx, 'otherfield', "New Value" );

Any other params that you would normally use with the param method are sent along through the index method. The return is the same as returned by param. See PTools::SDF::SDF.

Finally, when calling the index method on a compound index, pass a "compound" value for both the idxFieldName and the idxFieldValue parameters.

Example:

    @idx = ( 'prodnbr&xyzzy', $prodNbrValue ."&". $xyzzyValue );

    $value = $sdfObj->index( @idx, "otherfieldname" );

    $sdfObj->index( @idx, "otherfieldname", "New Value" );

recNumber ( IdxFieldName, IdxFieldValue )

This method returns the record number offset into the current PTools::SDF::SDF object.

The parameters are identical to the first two parameters to the index method, above.

Example:

    @idx = ('prodnbr',$prodNbrValue);

    $recNum = $sdfObj->recNumber( @idx );

recData ( IdxFieldName, IdxFieldValue )

Fetch the entire record indexed by RecNumber as a hash reference. This can then be used to access and update field values.

WARNING: Modifying data values in the returned hash reference will update the values in the corresponding data record.

The parameters are identical to the first two parameters to the index method, above.

This method is equivalent in function to the getRecEntry method in the PTools::SDF::SDF class.

Example:

    @idx = ('prodnbr',$prodNbrValue);

    $hashRef = $sdfObj->recData( @idx );

    $hashRef->{fieldname} = "new value";        # updates the $sdfObj, too.

getIndex ( IdxFieldName )

The getIndex method returns a hash reference that contains the internal mapping used to lookup record numbers based on the values for a given index field.

The parameter is identical to the first parameter to the index method, above.

Example:

    $hashRef = $sdfObj->getIndex( 'prodnbr' );

indexCount ( IdxFieldName )

This method is somewhat analogous to the count method in the PTools::SDF::SDF class. However, remember that the index may have been limited to a subset of records in the current object. As such the return value from these methods may not be equivalent.

The parameter is identical to the first parameter to the index method, above.

Example:

    $idxCount = $sdfObj->indexCount( 'prodnbr' )

indexDelete ( IdxFieldName, IdxFieldValue, FieldName )

Delete the value for a named data field within a record

The parameters are identical to the first three parameters to the index method, above.

Example:

    # Delete the value for the 'proddesc' field in the record
    # specified by the "@idx" array.

    @idx = ('prodnbr',$prodNbrValue);

    $sdfObj->indexDelete( @idx, 'proddesc');

sort ( Options )

The sort method is overridden in this class. Since record sorting usually rearranges the order of records in the file, any and all currently defined indices are removed.

The sort Options are passed through unchanged to whatever sort class happens to be in use with the current object.

Currently this method will not reestablish prior index keys so either perform any ncessary sorting prior to index initilization, or reinitialize indices after each sort.