NAME

CDB_File::BiIndex - index two sets of values against eachother.

SYNOPSIS

        use CDB_File::BiIndex;
        #test bi-index is initiated with CDB_Generator
        $index = new CDB_File::BiIndex "test";

        $index->lookup_first("USA");
        $index->lookup_second("Lilongwe");

DESCRIPTION

A CDB_File::BiIndex stores a set of relations from one set of strings to another. It's rather similar to a translators dictionary with a list of words in one language linked to words in the other language. The same word can occur in each language, but it's translations would often be different.

    I    <->  je
    {bar, pub}  <->  bar
    {truck, lorry, heavy goods vehicle} <-> camion

In this implementation it's just two parallel cdb hashes, which you have to generate in advance.

EXAMPLE

    use CDB_File::BiIndex::Generator;
    use CDB_File::BiIndex;
    $gen = new CDB_File::BiIndex::Generator "test";

    $gen->add_relation("John", "Jenny");
    $gen->add_relation("Roger", "Beth");
    $gen->add_relation("John", "Gregory");
    $gen->add_relation("Jemima", "Jenny")
    $gen->add_relation("John", "Gregory");

    $gen->finish();

    $index = new CDB_File::BiIndex::Generator "test";

    $index->lookup_first("Roger");
        ["Jenny"]
    $index->lookup_second("Jenny");
        ["John", "Jemima"]
    $index->lookup_second("John");
        []
    $index->lookup_first("John");
        ["Jenny", "Gregory"]

METHODS

CDB_File::BiIndex->new(<file>,[<file>])

        new (CLASS, database_filenamebase)
        new (CLASS, first_database_filename, second_database_filename)

New opens and sets up the databases.

$bi->lookup_first(<key>) $bi->lookup_second(<key>)

returns a reference to a list of values which are indexed against key, direction of the relation depending on which function is used.

ITERATORS

The iterators iterate over the different keys in the database. They skip repeated keys.

first_set_iterate(<key>) second_set_iterate(<key>)

set the key of the next value that will be returned

first_next([<last key>]) second_next([<last key>])

return the next key in the hash. If there has never been any iteration before we will return the first key from the database. If there has been iteration, we will return the key imediately following the key which was last returned.

If called with an argument, the key following that argument will be returned in any case, but if that argument is exactly the last key returned, we won't seek in the database (set_iterate would do that anyway).

BUGS

This module requires the version of the CDB_File perl module to be better than 0.86. Unfortunately, version 0.83 was given the version string "0.9" (and version 0.86 has the string '0.86'). This means that normal perl version checking will not give the correct warnings. There is a hardwired check that the version is not 0.9. I assume that future CDB_File modules won't use that version number, but if they do, then please edit inside the CDB_File::BiIndex perl module file its self and delete the section between the lines

  # delete from here ...

and

  # ... delete to here

the module will then hopefully work properly.

N.B. please only do that if you have verified that you have a newer version of the distribution than 0.86.

COPYING

This module may be distributed under the same terms as perl.