The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Array-OrdHash-1.02
River stage zero No dependents
++
/ Array::OrdHash

NAME

Array::OrdHash - ordered associative array with array-like, hash-like and OO interface.

SYNOPSIS

 use Array::OrdHash;

 $oh = Array::OrdHash->new;

 $oh->{'a'} = 'First';
 $oh->{'b'} = 'Second';
 $oh->{'c'} = 'Third';
 
 $oh->[0] = 'new First';
 $oh->[1] = 'new Second';
 $oh->[3] = 'Forth';    # (would be croaked)
 
 exists $oh->{'c'};
 exists $oh->[2];       # the same result

 delete $oh->{'c'};
 delete $oh->[2];       # the same result
 
 # inserting a list
 @LIST = ('d'=>'Forth', 'e'=>'Fifth', 'f'=>'Sixth');
 push @$oh, @LIST;
 
 unshift @$oh, ('i'=>'I', 'j'=>'J', 'k'=>'K');
 
 # iterating as a hash
 while (($key, $val) = each %$oh) {
  print "$key=", $val, "\n";
 }
 
 # iterating as a list (more efficient)
 while (($key, $val, $ind) = $oh->List) {
  print "($ind) $key = $val\n";
 }

 # iterating as an array
 foreach $val (@$oh) {
  print $val, "\n";
 }
 
  $oh->Reset();

 # pop, shift and splice
 $item = pop @$oh;
 $item = shift @$oh;
 @spliced = splice @$oh, $offset, $len [,LIST];
 
 # keys and values arrays
 @k = keys %$oh;
 @v = values %$oh;
 
 @k = $oh->Keys([LIST]);
 @v = $oh->Values([LIST]);
 
 # miscellaneous
 $oh->Sort( src=>'keys' );
 $oh->Sort( src=>'values DESC' );
 $oh->Sort( proc=>\&SortProcedure );
 
 $oh->Reorder(LIST);
 
 $oh->First();
 $oh->Last()
 
 $oh->Indices(LIST);
 
 $oh->Length();

DESCRIPTION

This module implements Perl arrays that have both numeric and string indices, similar to PHP arrays or Collections, therefore the array keys are unique strings.

The order in which the elements were added is preserved just like Tie::IxHash does this.

Both Perl array and Perl hash functions can be performed on a variable of this class. The elements of an array may be sorted both by keys and values, or with an external callback subroutine. They can also be reordered.

CONSTRUCTOR

new

 my $oh = Array::OrdHash->new([LIST]);

The new() constructor method instantiates a new Array::OrdHash object.

STANDARD INTERFACES

Hash Interface

A value of an Array::OrdHash object element can be set/read in a hash-like manner. When an element under the specified key does not exist then it is newly created:

 $oh->{'a'} = 'First';        $value = $oh->{'a'};
 $oh->{'b'} = 0.18;           $value = $oh->{'b'};
 $oh->{'c'} = [qw(3 .. 20)];  $value = $oh->{'c'};

 while (($key, $val) = each %$oh) {
  print "$key=", $val, "\n";
 }

The order in which the elements were added through the Standard Hash Interface is preserved. It is altered only when sorting or reordering.

Any Perl hash functions (delete, each, exists, keys, values) can be performed on an Array::OrdHash object just like on a Perl hash reference. The exception: when each is called outside the while cycle, or in the case of a premature end of a 'while - each' cycle, the "Reset" method must be called as soon as possible in order to reset the inner iterator. The returned value of the delete function also differs from the standard one.

delete

Deletes the Array::OrdHash object array element under the specified key. The returned value is an array reference representing the deleted index-value pair.

 $deleted_item = delete $oh->{ KEY };
 ($index, $value) = @$deleted_item;

Array Interface

A value of an already existing Array::OrdHash object element can be set/read in an array-like manner:

 $oh->[0] = 'First';        $value = $oh->[0];
 $oh->[1] = 0.18;           $value = $oh->[1];
 $oh->[2] = [qw(3 .. 20)];  $value = $oh->[2];

 foreach $val (@$oh) {
  print $val, "\n";
 }

An element with the specified index must already exist. It can previously be set through the "Hash interface" or with push, unshift or splice functions. An attempt to modify an element under unexisting index is croaked. However, negative indexes are acceptable within the limits of standard Perl arrays.

push, unshift

 @LIST = ('d'=>'Forth', 'e'=>'Fifth', 'f'=>'Sixth');
 push @$oh, @LIST;
 unshift @$oh, ('i'=>'I', 'j'=>'J', 'k'=>'K');

These functions insert a list to the end or to the beginning of Array::OrdHash object respectively:

The elements of the inserted list are treated as consecutive key-value pairs. The functions return the new number of items in the Array::OrdHash object array.

If a key in the list already exists in the Array::OrdHash object array, then its value is replaced with the supplied one, but its position is not changed.

pop, shift

 $item = pop @$oh;
 $item = shift @$oh;
 ($key, $value) = @$item;

These functions pops or shifts an Array::OrdHash object element. The returned value is an array reference representing the key-value pair.

splice

 @spliced = splice @$oh, $offset, $len [,LIST];

Does just similar as the standard splice function, but the elements of the inserted list are treated as consecutive key-value pairs. Returns the list of spliced items as consecutive key-value pairs.

The restictions for offset and length parameters are the same as for the standard splice function.

exists

 $exists = exists $oh->[INDEX];

This function acts just like the standard exists:

delete

 $deleted_item = delete $oh->[INDEX];
 ($key, $value) = @$deleted_item;

Deletes the Array::OrdHash object array element under the specified index. The returned value is an array reference representing the deleted key-value pair.

METHODS

First, Last

 $is_first = $oh->First();
 $is_last = $oh->Last();

Return 1 when the current item of the Array::OrdHash object during the hash-style iteration process has the first or the last position in the whole array respectively. Otherwise return undefined value.

Indices

 @indices = $oh->Indices(LIST);

Returns the indices of the keys specified by the LIST.

Keys, Values

 @k = $oh->Keys([LIST]);
 @v = $oh->Values([LIST]);

Return the array of keys or values of the Array::OrdHash object respectively. When the LIST of indices is specified then only the corresponding data are returned. If the LIST is omitted then all keys or values are returned.

Length

 $len = $oh->Length();

Returns the number of items in the Array::OrdHash object array.

List

Iterates through the Array::OrdHash object array. Returns next key-value pair plus the current item's index. This method is some more efficient than the hash-style while - each cycle.

When the cycle ends prematurely, then it is necessary to call "Reset" method as soon as possible to reset the inner iterator.

 while (($key, $val, $ind) = $oh->List) {
  print "($ind) $key = $val\n";
 }

Reorder

 $oh->Reorder(LIST);

Reorders the items in the Array::OrdHash object array according to the specified LIST of keys. All items of the Array::OrdHash object array whose keys are not present in the LIST are deleted. Elements of the LIST, which are not present in the initial Array::OrdHash object array as keys, are ignored.

Reset

Resets the inner iterating variable of the Array::OrdHash object. It is required to be called in cases when the cycles 'while - each' or "List" are prematurely ended.

Sort

 $oh->Sort( ['src'=>'(keys|values)[ DESC]'][,'proc'=>\&SORT_PROCEDURE] );

Sorts the Array::OrdHash object array.

Parameters:

src (optional) - by what must the array be sorted. Can be 'keys' (default) or 'values'. Sorting is case sensitive. If ' DESC' is additionally given then the sorting order is descending, otherwise the order is ascending.

proc (optional) - a reference to an external sort procedure. When supplied then the presence of ' DESC' is ignored.

EXAMPLE

 use Array::OrdHash;

 $oh = Array::OrdHash->new('a'=>'FIRST', 'b'=>'SECOND', 'c'=>'THIRD', 'd'=>'FORTH');
 
 # replacing the third element (index 2) with another key/value pair
 
 @old_pair = splice @$oh, 2, 1, 'c new', 'THIRD new';

BUGS & CAVEATS

There no known bugs at this time, but this doesn't mean there are aren't any.

AUTHOR

Vladimir Surin <brexs@yandex.ru>

COPYRIGHT & LICENSE

Copyright (C) 2009-2010 Vladimir Surin. All Rights Reserved.

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

VERSION

Version 1.02

SEE ALSO

perlfunc, Tie::IxHash