NAME

App::Chart::Tie::Hash::Union -- union of multiple hashes

SYNOPSIS

use App::Chart::Tie::Hash::Union;
my %h1 = (a => 1, b => 2);
my %h2 = (x => 3, y => 3);
my %union;
tie %union, \%h1, \%h2;
print $union{a},"\n";  # entry in %h1
print $union{y},"\n";  # entry in %h2

DESCRIPTION

App::Chart::Tie::Hash::Union makes a hash present the keys and values of a given set of other underlying hash tables. Accessing the tied hash looks in each of those hashes for the desired key. The tied hash hold nothing of it's own but looks dynamically at the underlying hashes, so it reflects their current contents at any given time.

$tiedhash{$key}

Fetching looks in each unioned hash for the first with exists $h-{$key}>.

$tiedhash{$key} = $value

Storing looks in each unioned hash for one with exists $h-{$key}> and stores to that entry. If none have $key already then a new entry is made in the first unioned hash. If there are no unioned hashes the store croaks.

delete $tiedhash{$key}

Deleting deletes $key from each of the unioned hashes.

clear %tiedhash

Clearing clears each unioned hash.

keys %tiedhash

Returns the keys of all the unioned hashes.

each %tiedhash

Iterates the unioned hashes. Currently this is implemented using a corresponding each on those underly hashes, so don't call each, keys or values on those or it will upset the iterated position of the tied hash.

scalar %tiedhash

In scalar context the tied hash returns bucket usage counts like 3/64 like an ordinary hash, made by adding up the unioned hashes. If a unioned hash returns something other than a bucket count in scalar context (which can happen if it in turn is also a tied hash) then it's counted as 1/1 if true or 0/0 if false.

In Perl 5.8 and earlier tied hashes which don't implement the SCALAR method always return 0 as if it's empty, when it may not be. This of course will propagate up through a App::Chart::Tie::Hash::Union to make it appear empty when it may not be.

FUNCTIONS

tie %hash, 'App::Chart::Tie::Hash::Union', \%h1, \%h2, ...

Tie hash %hash to present the contents of the given %h1, %h2, etc.

$hashref = App::Chart::Tie::Hash::Union->new (\%h1, \%h2, ...)

Return a ref to a newly created hash table tied to the given %h1, %h2, etc. For example

my $href = App::Chart::Tie::Hash::Union->new (\%h1, \%h2);

is the same as

tie (my %hash, 'App::Chart::Tie::Hash::Union', \%h1, \%h2);
my $href = \%hash;

If you want your own %hash as such then the plain tie is easier. If you want an hashref to pass around to other funcs then new saves a line of code.

Object Methods

The tie object associated with the tied hash, as returned by the tie or obtained later with tied, has the following methods.

$thobj->add (\%h3, ...)

Add further hash tables to the union.

@list = $thobj->hashes()

Return a list of hashrefs which are currently being unioned.

SEE ALSO

Hash::Union, Hash::Merge