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, <fabrice at dulaunoy.com>

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.