NAME

Genezzo::PushHash::hph.pm - an impure virtual class module that defines a *hierarchical* "push hash", a hash that generates its own unique key for each value. Values are "pushed" into the hash, similar to pushing into an array. Hierarchical pushhashes must be supplied with a factory method which manufactures additional pushhashes as necessary.

SYNOPSIS

use Genezzo::PushHash::hph;

sub make_fac {
   my $tclass = shift;
   my %args = (
               @_);

   my %td_hash1  = ();

   my $newfunc = 
       sub {
           my $tiehash1 = 
               tie %td_hash1, $tclass, %args;

           return $tiehash1;
       };
   return $newfunc;
}

my $fac1 = make_fac('Genezzo::PushHash::PHFixed');

%args = 
   (
    factory  => $fac1
   );

my %tied_hash = ();

my $tie_val = 
   tie %tied_hash, 'Genezzo::PushHash::hph', %args;

my $newkey = $tie_val->HPush("this is a test");

$tied_hash{$newkey} = "update this entry";

my $getcount = $tie_val->HCount();

DESCRIPTION

A hierarchical pushhash (hph) is a pushhash built upon a collection of other pushhashes. A push into the top-level hash is routed into one of the bottom hashes. If the bottom hashes are full (push fails), the top-level pushhash uses the factory method to create or obtain a new pushhash.

The hph uses a split-level identifier scheme to route STOREs and FETCHes to the appropriate bottom level hashes. For example, the top-level hash might have three children identified with integer prefixes 1, 2, and 3. Pushes into hash 1 would return keys 1/1, 1/2, 1/3, etc. until it fills up, at which point the top-level hash would redirect pushes into hash 2, generating keys 2/1, 2/2, 2/3, etc. When key "1/2" is fetched, the top-level hash "splits" the key and directs child hash "1" to fetch key "2". Iteration over keys is similar: the parent interates over the set of child hashes, and each child iterates over its set of keys.

You may construct hierarchical pushhashes of arbitrary depth.

EXPORT

RIDSEP -- (Row) Identifier Separator character - "/" by default.

RIDSEPRX -- Regular Expression for RIDSEP - used to handle case of "." as separator, or other regexp metachars, for internal RID join and split operations.

MAXCOUNT -- no max if -1, else maximum number of elements for this hash

CONCEPTS and INTERNALS - useful for implementors

A hph is constructed of N pushhash "chunks", and the elements of each chunk are referred to as "slices". Typically, one chunk is "current" -- we push into the current chunk until it fills up, at which point the hph attempts to make a new one. Key identifiers are called "rids", and a rid may have multiple parts, e.g. "1/2/3/4". When this rid is split, the first part, "1", is the "chunk number", and the remainder "2/3/4" is the "slice number". The basic implementation uses positive integers for chunk and slice numbers -- zeroes reset the FIRSTKEY/NEXTKEY mechanism and may indicate errors, among other things.

The following methods are private to hph and should only be used in the construction of subclasses and friend classes.

_currchunkno

get the number of the current (active) chunk. NOTE WELL: when constructing push hash classes, remember that "current" has the specific meaning of the insert high-water mark -- the "current" insertion point. It's not necessarily the last chunk that you were using, or the chunk that is currently cached.

_get_current_chunk

return the current chunk

_make_new_chunk

construct a new chunk and return it

_get_a_chunk

given a chunk number, returns the chunk

_get_chunk_and_slice

given a rid, it returns the actual chunk (not the chunk number) and the slice number.

_joinrid/_splitrid

construct and deconstruct rid's from/to the chunknumber and the slice number using the rid separator regular expression.

_First_Chunkno/_Next_Chunkno

methods to iterate over the chunk numbers.

AUTHOR

Jeffrey I. Cohen, jcohen@genezzo.com

SEE ALSO

Genezzo::PushHash::PushHash, perl(1).

Copyright (c) 2003, 2004, 2005, 2006 Jeffrey I Cohen. All rights reserved.

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA

Address bug reports and comments to: jcohen@genezzo.com

For more information, please visit the Genezzo homepage at http://www.genezzo.com