/ 
Array-AsHash-0.10
River stage zero No dependents
/ Array::AsHash

NAME

Array::AsHash - Treat arrays as a hashes, even if you need references for keys.

VERSION

Version 0.10

SYNOPSIS

 use Array::AsHash;

 my $array = Array::AsHash->new({
     array => \@array,
     clone => 1, # optional
 });

 while (my ($key, $value) = $array->each) {
     # sorted
     ...
 }

 my $value = $array->get($key);
 $array->put($key, $value);
 
 if ( $array->exists($key) ) {
     ...
 }

 $array->delete($key);

DESCRIPTION

Sometimes we have an array that we need to treat as a hash. We need the data ordered, but we don't use an ordered hash because it's already an array. Or it's just quick 'n easy to run over array elements two at a time.

Because we take a reference to what you pass to the constructor (or use the reference you pass), you may wish to copy your data if you do not want it altered (the data are not altered except through the publicly available methods of this class).

Also, we keep the array an array. This does mean that things might get a bit slow if you have a large array, but it also means that you can use references (including objects) as "keys". For the general case of fetching and storing items, however, you'll find the operations are O(1). Behaviors which can affect the entire array are often O(N).

EXPORT

None.

OVERLOADING

Note that the boolean value of the object has been overloaded. An empty array object will report false in boolean context:

my $array = Array::AsHash->new;
if ($array) {
  # never gets here
}

CONSTRUCTOR

new

my $array = Array::AsHash->new( { array => \@array } );

Returns a new Array::AsHash object. If an array is passed to new, it must contain an even number of elements. This array will be treated as a set of key/value pairs:

my @array = qw/foo bar one 1/;
my $array = Array::AsHash->new({array => \@array});
print $array->get('foo'); # prints 'bar'

Note that the array is stored internally and changes to the Array::AsHash object will change the array that was passed to the constructor as an argument. If you do not wish this behavior, clone the array beforehand or ask the constructor to clone it for you.

my $array = Array::AsHash->new(
   {
       array => \@array,
       clone => 1, # optional
   }
);

Internally, we use the Clone module to clone the array. This will not always work if you are attempting to clone objects (inside-out objects are particularly difficult to clone). If you encounter this, you will need to clone the array yourself. Most of the time, however, it should work.

Of course, you can simply create an empty object and it will still work.

my $array = Array::AsHash->new;
$array->put('foo', 'bar');

HASH-LIKE METHODS

The following methods allow one to treat an Array::AsHash object more-or-less like a hash.

keys

my @keys = $array->keys;

Returns the "keys" of the array. Returns an array reference in scalar context.

values

my @values = $array->values;

Returns the "values" of the array. Returns an array reference in scalar context.

delete

my @values = $array->delete(@keys);

Deletes the given @keys from the array. Returns the values of the deleted keys. In scalar context, returns an array reference of the keys.

As a "common-case" optimization, if only one key is requested for deletion, deletion in scalar context will result in the one value (if any) being returned instead of an array reference.

my $deleted = $array->delete($key); # returns the value for $key
my $deleted = $array->delete($key1, $key2); # returns an array reference

Non-existing keys will be silently ignored.

each

while ( my ($key, $value) = $array->each ) {
   # iterate over array like a hash
}

Lazily returns keys and values, in order, until no more are left. Every time each() is called, will automatically increment to the next key value pair. If no more key/value pairs are left, will reset itself to the first key/value pair.

As with a regular hash, if you do not iterate over all of the data, the internal pointer will be pointing at the next key/value pair to be returned. If you need to restart from the beginning, call the reset_each method.

kv

while ( my ($key, $value) = $array->kv ) {
   # iterate over array like a hash
}

kv is a synonym for each.

reset_each

$array->reset_each;

Resets the each iterator to point to the beginning of the array.

exists

if ($array->exists($thing)) { ... }

Returns true if the given $thing exists in the array as a key.

get

my $value = $array->get($key);

Returns the value associated with a given key, if any.

put

$array->put($key, $value);

Sets the value for a given $key. If the key does not already exist, this pushes two elements onto the end of the array.

hcount

my $pair_count = $array->hcount;

Returns the number of key/value pairs in the array.

hindex

my $index = $array->hindex('foo');

Returns the hash index of a given key, if the keys exists. The hash index is the array index divided by 2. In other words, it's the index of the key/value pair.

ARRAY-LIKE METHODS

The following methods allow one to treat a Array::AsHash object more-or-less like an array.

shift

my ($key, $value) = $array->shift;

Removes the first key/value pair, if any, from the array and returns it. Returns an array reference in scalar context.

pop

my ($key, $value) = $array->pop;

Removes the last key/value pair, if any, from the array and returns it. Returns an array reference in scalar context.

unshift

$array->unshift(@kv_pairs);

Takes an even-sized list of key/value pairs and attempts to unshift them onto the front of the array. Will croak if any of the keys already exists.

push

$array->unshift(@kv_pairs);

Takes an even-sized list of key/value pairs and attempts to push them onto the end of the array. Will croak if any of the keys already exists.

insert_before

$array->insert_before($key, @kv_pairs);

Similar to splice(), this method takes a given $key and attempts to insert an even-sized list of key/value pairs before the given key. Will croak if $key does not exist or if @kv_pairs is not an even-sized list.

$array->insert_before($key, this => 'that', one => 1);

insert_after

$array->insert_after($key, @kv_pairs);

This method takes a given $key and attempts to insert an even-sized list of key/value pairs after the given key. Will croak if $key does not exist or if @kv_pairs is not an even-sized list.

$array->insert_after($key, this => 'that', one => 1);

acount

my $count = $array->acount;

Returns the number of elements in the array.

aindex

my $count = $array->aindex('foo');

Returns the aray index of a given key, if the keys exists.

OTHER METHODS

The following methods really don't match the aforementioned categories.

get_array

my @array = $array->get_array;

Returns the array in the object. Returns an array reference in scalar context. Note that altering the returned array can affect the internal state of the Array::AsHash object and will probably break it. You should usually only get the underlying array as the last action before disposing of the object. Otherwise, attempt to clone the array with the clone method and use that array.

my @array = $array->clone->get_array;

clone

my $array2 = $array->clone;

Attempts to clone (deep copy) and return a new object. This may fail if the array contains objects which Clone cannot handle.

WHY NOT A TIED HASH?

You may very well find that a tied hash fits your purposes better and there's certainly nothing wrong with them. Personally, I do not use tied variables unless absolutely necessary because ties are frequently buggy, they tend to be slow and they take a perfectly ordinary variable and make it hard to maintain. Return a tied variable and some poor maintenance programmer is just going to see an hash and they'll get awfully confused when their code isn't doing quite what they expect.

Of course, this module provides a richer interface than a tied hash would, but that's just another benefit of using a proper class instead of a tie.

AUTHOR

Curtis "Ovid" Poe, <ovid@cpan.org>

BUGS

Please report any bugs or feature requests to bug-array-ashash@rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Array-AsHash. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SEE ALSO

Clone, Tie::IxHash, Class::Std (how this module is implemented).

COPYRIGHT & LICENSE

Copyright 2005 Curtis "Ovid" Poe, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.