NAME

Array::Assign - Assign and extract array elements by names.

SYNOPSIS

    use Array::Assign;
    

procedural interface:

    my @array;
   arry_assign_i @array, 4 => "Fifth", 0 => "First";
   ok $array[4] eq "Fifth" && $array[0] eq "First";
   
   my $mappings = { fifth => 4, second => 1 };
   
   arry_assign_s @array, $mappings, fifth => "hi", second => "bye";
   ok $array[4] eq "hi" && $array[1] eq "bye";
   
   my ($fooval,$bazval);
   
   my @arglist = qw(first foo bar baz);
   arry_extract_i @arglist, 3 => \$bazval, 1 => \$fooval;
   ok $fooval eq "foo" && $bazval eq "baz";
   
   my $emapping = { foovalue => 1, bazvalue => 3 };
   arry_extract_s @arglist, $emapping, foovalue => \$fooval, bazvalue => \$bazval;
   ok $fooval eq 'foo' && $bazval eq 'baz';
    

OO interface:

    my @array;
    my $assn = Array::Assign->new(qw(foo bar baz));
    $assn->assign_s(\@array, foo => "hi", baz => "bye");
    ok($array[0] eq 'hi' && $array[2] eq 'bye');
    
    $assn->assign_i(\@array, 0 => "first", 2 => "last");
    ok($array[0] eq 'first' && $array[2] eq 'last');
    
    my ($firstval,$lastval);
    $assn->extract_s(\@array, foo => \$firstval, baz => \$lastval);
    ok($firstval eq 'first' && $lastval eq 'last');
    $assn->extract_i(\@array, 2 => \$lastval, 0 => \$firstval);
    ok($firstval eq 'first' && $lastval eq 'last');

DESCRIPTION

Array::Assign contains an object and various utilities to access and modify array indexes based on un-ordered and hash-like string aliases.

Its main use is for sanely modifying arrays which are needed for other APIs, but are not worth the while making classes for.

Array::Assign offers both a procedural and object-oriented interface, which are both documented below:

OO Interface

new(namelist)

Construct a new Array::Assign object with a namelist. A namelist can either be an array (or reference to one), in which case the index matching is implict to the position of each name in namelist.

If namelist is a hash reference, then its keys are taken to be names, and its values are taken to be indices.

assign_s(\@target, alias => value...)

Assign values to @target based on the mappings passed to namelist in new.

It is an error (and will die) if you pass an alias which was not previously specified in new

assign_i(\@target, index => value..)

For each index, $targed[$index] is assigned <value>. This does not strictly have anything to do with the object, but is included for API symmetry.

Additionally, sanity checking is placed on the size of the index. If an index is accidentally too large, your program (and possibly machine) will crash to to excessive memory allocation. To increase the 'sanity' limit, you can set the global package variable $Array::Assign::MAX_IDX.

extract_s(\@source, alias => \$target..)

For each alias, assign the value of $source[$alias_idx] to $$target, which is a reference. This is effectively the reverse of "assign_s".

extract_i(\@source, idx => \$target..)

Reverse of "assign_i".

Procedural Interface

arry_assign_s @arry, $mapping, alias => value..

arry_assign_i @arry, idx => value..

arry_extract_s @source, $mapping, alias => \$target..

arry_extract_i @source, idx => \$target..

BUGS

Probably quite slow.

AUTHOR AND COPYRIGHT

Copyright (C) 2012 M. Nunberg.

You may use and distribute this software under the same terms as Perl itself.

cpanm Array::Assign

perl -MCPAN -e shell
install Array::Assign