NAME Tie::Array::Cavity - create an array where key are aggregated by step ( and optionally could start with an offset ) VERSION Version 0.02 SYNOPSIS A Tie array module where the keys ( indexes ) are like a cavity bucket and collect all the keys from a specific neighbor range Perhaps a little code snippet. use Tie::Array::Cavity; my $tied = tie my @a, 'Tie::Array::Cavity' , 10 , 5; $a[1] = 1; $a[15] = 15; $a[25]=25; $a[24]=240; $a[31]=31; $a[40]=40; Result: [ 1, 15, 240, 31, 40 ]; as a consequence, $a[1]; and $a[2]; refer to the same element of the array In the previous code $a[25]=25; set the the 3 element with the value 25,but $a[24]=240; over write the 3 element with the value 240. !!!!! BECARE !!!!! lvalue update are not working as expected. In the example above, $a[24]++; is setting the second element of the array with '1' because fetching the value $a[24] return the 24 element of the array. It is "by design" to allow normal iteration on the array ( e.g. foreach ( @a ) or Dumper(\@a ) ) EXPORT A list of functions that can be exported. You can delete this section if you don't export anything, such as for a purely object-oriented module. SUBROUTINES/METHODS TIEARRAY my $tied = tie my @a, 'Tie::Array::Cavity' , 10 , 5; Tie::Array::Cavity tie an array where the keys are in a range Two extra parameters are allowed: 1) the granularity of the key range ( default = 0 ) 2) the initial offset ( default = 0 ) STORE Add an element in the array at the ARRAY index with the cavity behavior; my $tied = tie my @a, 'Tie::Array::Cavity' , 10 , 5; $myarray[31] , 45646; store 45646 at the 3 place in the array [ ..., ..., 45646, ..., ] STORESIZE this Sets the total number of items in the tied array associated with object *this*. FETCHSIZE this Returns the total number of items in the tied array associated with object *this*. (Equivalent to `scalar(@array)'). FETCHCAVITY this , index Retrieve the value in *index* for the tied array associated with object *this*. But the index is calculated with the cavity feature. FETCHKEY this , index Return the calculated real key used by the cavity feature. FETCHKEYCAVITY this , index Return the calculated cavity key related to a normal array index. FETCH this , index Retrieve the value in *index* for the tied array associated with object *this*. POP this Remove the last element of the array and return it. SHIFT this Remove the first element of the array and return it. PUSH this, LIST Append elements of *LIST* to the array. UNSHIFT this, LIST Insert *LIST* elements at the beginning of the array, moving existing elements up to make room. EXISTSCAVITY this, key Verify that the element at index *key* exists in the tied array this. The key is using the cavity feature. EXISTS this, key Verify that the element at index *key* exists in the tied array this. DELETECAVITY this, key Delete the element at index *key* from the tied array this. The key is using the cavity feature. DELETE this, key Delete the element at index *key* from the tied array this. SPLICECAVITY this, offset, length, LIST Perform the equivalent of `splice' on the array. *offset* is optional and defaults to zero, negative values count back from the end of the array. *length* is optional and defaults to rest of the array. *LIST* may be empty. Returns a list of the original *length* elements at *offset*. The *offset* and *length* is using the cavity feature. SPLICE this, offset, length, LIST Perform the equivalent of `splice' on the array. *offset* is optional and defaults to zero, negative values count back from the end of the array. *length* is optional and defaults to rest of the array. *LIST* may be empty. Returns a list of the original *length* elements at *offset*. USAGE One of the useful usage of this module is for aggregating data coming for a time series by some slice. Example: You've got a lot of data polled each second for a day, and you would like to aggregate the result by 5 minutes starting at the beginning of the day: my %data = ( 1351551600 => 10, 1351551601 => 15, 1351551950 => 5 ); my $tied1= tie my @d, 'Tie::Array::Cavity' , 300 ,1351551600 ; my $start = 1351551600; foreach my $t ( keys %data ) { $d[$t]= $tied1->FETCHCAVITY($t)+ $data{ $t }; } say Dumper(\@d); AUTHOR DULAUNOY Fabrice, `' BUGS Please report any bugs or feature requests to `bug-tie-array-Cavity at rt.cpan.org', or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Tie-Array-Cavity. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes. SUPPORT You can find documentation for this module with the perldoc command. perldoc Tie::Array::Cavity You can also look for information at: * RT: CPAN's request tracker (report bugs here) http://rt.cpan.org/NoAuth/Bugs.html?Dist=Tie-Array-Cavity * AnnoCPAN: Annotated CPAN documentation http://annocpan.org/dist/Tie-Array-Cavity * CPAN Ratings http://cpanratings.perl.org/d/Tie-Array-Cavity * Search CPAN http://search.cpan.org/dist/Tie-Array-Cavity/ ACKNOWLEDGEMENTS LICENSE AND COPYRIGHT Copyright 2012 DULAUNOY Fabrice. This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License. See http://dev.perl.org/licenses/ for more information.