berkeleydb.pod

BerkeleyDB源码

                [ -Encrypt       => { Password => "string",
	                              Flags    => number }, ],
                # BerkeleyDB::Hash specific
                [ -Ffactor       => number,]
                [ -Nelem         => number,]
                [ -Hash          => code reference,]
                [ -DupCompare    => code reference,]

and this

    [$db =] tie %hash, 'BerkeleyDB::Hash', 
                [ -Filename      => "filename", ]
                [ -Subname       => "sub-database name", ]
                [ -Flags         => flags,]
                [ -Property      => flags,]
                [ -Mode          => number,]
                [ -Cachesize     => number,]
                [ -Lorder        => number,]
                [ -Pagesize      => number,]
                [ -Env           => $env,]
                [ -Txn           => $txn,]
                [ -Encrypt       => { Password => "string",
	                              Flags    => number }, ],
                # BerkeleyDB::Hash specific
                [ -Ffactor       => number,]
                [ -Nelem         => number,]
                [ -Hash          => code reference,]
                [ -DupCompare    => code reference,]


When the "tie" interface is used, reading from and writing to the database
is achieved via the tied hash. In this case the database operates like
a Perl associative array that happens to be stored on disk.

In addition to the high-level tied hash interface, it is possible to
make use of the underlying methods provided by Berkeley DB

=head2 Options

In addition to the standard set of options (see L<COMMON OPTIONS>)
B<BerkeleyDB::Hash> supports these options:

=over 5

=item -Property

Used to specify extra flags when opening a database. The following
flags may be specified by bitwise OR'ing together one or more of the
following values:

B<DB_DUP>

When creating a new database, this flag enables the storing of duplicate
keys in the database. If B<DB_DUPSORT> is not specified as well, the
duplicates are stored in the order they are created in the database.

B<DB_DUPSORT>

Enables the sorting of duplicate keys in the database. Ignored if
B<DB_DUP> isn't also specified.

=item -Ffactor

=item -Nelem

See the Berkeley DB documentation for details of these options.

=item -Hash

Allows you to provide a user defined hash function. If not specified, 
a default hash function is used. Here is a template for a user-defined
hash function

    sub hash
    {
        my ($data) = shift ;
        ...
        # return the hash value for $data
	return $hash ;
    }

    tie %h, "BerkeleyDB::Hash", 
        -Filename => $filename, 
    	-Hash     => \&hash,
	...

See L<""> for an example.

=item -DupCompare

Used in conjunction with the B<DB_DUPOSRT> flag. 

    sub compare
    {
	my ($key, $key2) = @_ ;
        ...
        # return  0 if $key1 eq $key2
        #        -1 if $key1 lt $key2
        #         1 if $key1 gt $key2
        return (-1 , 0 or 1) ;
    }

    tie %h, "BerkeleyDB::Hash", 
        -Filename   => $filename, 
	-Property   => DB_DUP|DB_DUPSORT,
    	-DupCompare => \&compare,
	...

=back


=head2 Methods

B<BerkeleyDB::Hash> only supports the standard database methods.
See L<COMMON DATABASE METHODS>.

=head2 A Simple Tied Hash Example

    use strict ;
    use BerkeleyDB ;
    use vars qw( %h $k $v ) ;

    my $filename = "fruit" ;
    unlink $filename ;
    tie %h, "BerkeleyDB::Hash",
                -Filename => $filename,
		-Flags    => DB_CREATE
        or die "Cannot open file $filename: $! $BerkeleyDB::Error\n" ;

    # Add a few key/value pairs to the file
    $h{"apple"} = "red" ;
    $h{"orange"} = "orange" ;
    $h{"banana"} = "yellow" ;
    $h{"tomato"} = "red" ;

    # Check for existence of a key
    print "Banana Exists\n\n" if $h{"banana"} ;

    # Delete a key/value pair.
    delete $h{"apple"} ;

    # print the contents of the file
    while (($k, $v) = each %h)
      { print "$k -> $v\n" }

    untie %h ;

here is the output:

    Banana Exists
    
    orange -> orange
    tomato -> red
    banana -> yellow

Note that the like ordinary associative arrays, the order of the keys
retrieved from a Hash database are in an apparently random order.

=head2 Another Simple Hash Example

Do the same as the previous example but not using tie.

    use strict ;
    use BerkeleyDB ;

    my $filename = "fruit" ;
    unlink $filename ;
    my $db = new BerkeleyDB::Hash
                -Filename => $filename,
		-Flags    => DB_CREATE
        or die "Cannot open file $filename: $! $BerkeleyDB::Error\n" ;

    # Add a few key/value pairs to the file
    $db->db_put("apple", "red") ;
    $db->db_put("orange", "orange") ;
    $db->db_put("banana", "yellow") ;
    $db->db_put("tomato", "red") ;

    # Check for existence of a key
    print "Banana Exists\n\n" if $db->db_get("banana", $v) == 0;

    # Delete a key/value pair.
    $db->db_del("apple") ;

    # print the contents of the file
    my ($k, $v) = ("", "") ;
    my $cursor = $db->db_cursor() ;
    while ($cursor->c_get($k, $v, DB_NEXT) == 0)
      { print "$k -> $v\n" }

    undef $cursor ;
    undef $db ;

=head2 Duplicate keys

The code below is a variation on the examples above. This time the hash has
been inverted. The key this time is colour and the value is the fruit name.
The B<DB_DUP> flag has been specified to allow duplicates.

    use strict ;
    use BerkeleyDB ;

    my $filename = "fruit" ;
    unlink $filename ;
    my $db = new BerkeleyDB::Hash
                -Filename => $filename,
		-Flags    => DB_CREATE,
		-Property  => DB_DUP
        or die "Cannot open file $filename: $! $BerkeleyDB::Error\n" ;

    # Add a few key/value pairs to the file
    $db->db_put("red", "apple") ;
    $db->db_put("orange", "orange") ;
    $db->db_put("green", "banana") ;
    $db->db_put("yellow", "banana") ;
    $db->db_put("red", "tomato") ;
    $db->db_put("green", "apple") ;

    # print the contents of the file
    my ($k, $v) = ("", "") ;
    my $cursor = $db->db_cursor() ;
    while ($cursor->c_get($k, $v, DB_NEXT) == 0)
      { print "$k -> $v\n" }

    undef $cursor ;
    undef $db ;

here is the output:

    orange -> orange
    yellow -> banana
    red -> apple
    red -> tomato
    green -> banana
    green -> apple

=head2 Sorting Duplicate Keys

In the previous example, when there were duplicate keys, the values are
sorted in the order they are stored in. The code below is
identical to the previous example except the B<DB_DUPSORT> flag is
specified.

    use strict ;
    use BerkeleyDB ;

    my $filename = "fruit" ;
    unlink $filename ;
    my $db = new BerkeleyDB::Hash
                -Filename => $filename,
		-Flags    => DB_CREATE,
		-Property  => DB_DUP | DB_DUPSORT
        or die "Cannot open file $filename: $! $BerkeleyDB::Error\n" ;

    # Add a few key/value pairs to the file
    $db->db_put("red", "apple") ;
    $db->db_put("orange", "orange") ;
    $db->db_put("green", "banana") ;
    $db->db_put("yellow", "banana") ;
    $db->db_put("red", "tomato") ;
    $db->db_put("green", "apple") ;

    # print the contents of the file
    my ($k, $v) = ("", "") ;
    my $cursor = $db->db_cursor() ;
    while ($cursor->c_get($k, $v, DB_NEXT) == 0)
      { print "$k -> $v\n" }

    undef $cursor ;
    undef $db ;

Notice that in the output below the duplicate values are sorted.

    orange -> orange
    yellow -> banana
    red -> apple
    red -> tomato
    green -> apple
    green -> banana

=head2 Custom Sorting Duplicate Keys

Another variation 

TODO

=head2 Changing the hash

TODO

=head2 Using db_stat

TODO

=head1 BerkeleyDB::Btree

Equivalent to calling B<db_open> with type B<DB_BTREE> in Berkeley DB 2.x and
calling B<db_create> followed by B<DB-E<gt>open> with type B<DB_BTREE> in
Berkeley DB 3.x or greater. 

Two forms of constructor are supported:


    $db = new BerkeleyDB::Btree
                [ -Filename      => "filename", ]
                [ -Subname       => "sub-database name", ]
                [ -Flags         => flags,]
                [ -Property      => flags,]
                [ -Mode          => number,]
                [ -Cachesize     => number,]
                [ -Lorder        => number,]
                [ -Pagesize      => number,]
                [ -Env           => $env,]
                [ -Txn           => $txn,]
                [ -Encrypt       => { Password => "string",
	                              Flags    => number }, ],
                # BerkeleyDB::Btree specific
                [ -Minkey        => number,]
                [ -Compare       => code reference,]
                [ -DupCompare    => code reference,]
                [ -Prefix        => code reference,]

and this

    [$db =] tie %hash, 'BerkeleyDB::Btree', 
                [ -Filename      => "filename", ]
                [ -Subname       => "sub-database name", ]
                [ -Flags         => flags,]
                [ -Property      => flags,]
                [ -Mode          => number,]
                [ -Cachesize     => number,]
                [ -Lorder        => number,]
                [ -Pagesize      => number,]
                [ -Env           => $env,]
                [ -Txn           => $txn,]
                [ -Encrypt       => { Password => "string",
	                              Flags    => number }, ],
                # BerkeleyDB::Btree specific
                [ -Minkey        => number,]
                [ -Compare       => code reference,]
                [ -DupCompare    => code reference,]
                [ -Prefix        => code reference,]

=head2 Options

In addition to the standard set of options (see L<COMMON OPTIONS>)
B<BerkeleyDB::Btree> supports these options:

=over 5

=item -Property

Used to specify extra flags when opening a database. The following
flags may be specified by bitwise OR'ing together one or more of the
following values:

B<DB_DUP>

When creating a new database, this flag enables the storing of duplicate
keys in the database. If B<DB_DUPSORT> is not specified as well, the
duplicates are stored in the order they are created in the database.

B<DB_DUPSORT>

Enables the sorting of duplicate keys in the database. Ignored if
B<DB_DUP> isn't also specified.

=item Minkey

TODO

=item Compare

Allow you to override the default sort order used in the database. See
L<"Changing the sort order"> for an example.

    sub compare
    {
	my ($key, $key2) = @_ ;
        ...
        # return  0 if $key1 eq $key2
        #        -1 if $key1 lt $key2
        #         1 if $key1 gt $key2
        return (-1 , 0 or 1) ;
    }

    tie %h, "BerkeleyDB::Hash", 
        -Filename   => $filename, 
    	-Compare    => \&compare,
	...

=item Prefix

    sub prefix
    {
	my ($key, $key2) = @_ ;
        ...
        # return number of bytes of $key2 which are 
        # necessary to determine that it is greater than $key1
        return $bytes ;
    }

    tie %h, "BerkeleyDB::Hash", 
        -Filename   => $filename, 
    	-Prefix     => \&prefix,
	...
=item DupCompare

    sub compare
    {
	my ($key, $key2) = @_ ;
        ...
        # return  0 if $key1 eq $key2
        #        -1 if $key1 lt $key2
        #         1 if $key1 gt $key2
        return (-1 , 0 or 1) ;
    }

    tie %h, "BerkeleyDB::Hash", 
        -Filename   => $filename, 
    	-DupCompare => \&compare,
	...

=back

=head2 Methods

B<BerkeleyDB::Btree> supports the following database methods.
See also L<COMMON DATABASE METHODS>.

All the methods below return 0 to indicate success.

=over 5

=item $status = $db->db_key_range($key, $less, $equal, $greater [, $flags])

Given a key, C<$key>, this method returns the proportion of keys less than 
C<$key> in C<$less>, the proportion equal to C<$key> in C<$equal> and the
proportion greater than C<$key> in C<$greater>.

The proportion is returned as a double in the range 0.0 to 1.0.

=back

=head2 A Simple Btree Example

The code below is a simple example of using a btree database.

    use strict ;
    use BerkeleyDB ;

    my $filename = "tree" ;
    unlink $filename ;
    my %h ;
    tie %h, 'BerkeleyDB::Btree',
    		-Filename   => $filename,
	        -Flags      => DB_CREATE
      or die "Cannot open $filename: $! $BerkeleyDB::Error\n" ;

    # Add a key/value pair to the file
    $h{'Wall'} = 'Larry' ;
    $h{'Smith'} = 'John' ;
    $h{'mouse'} = 'mickey' ;
    $h{'duck'}  = 'donald' ;

    # Delete
    delete $h{"duck"} ;

    # Cycle through the keys printing them in order.
    # Note it is not necessary to sort the keys as
    # the btree will have kept them in order automatically.
    foreach (keys %h)
      { print "$_\n" }

    untie %h ;

Here is the output from the code above. The keys have been sorted using
Berkeley DB's default sorting algorithm.

    Smith