NAME

Data::TableAutoSum - Table that calculates the results of rows and cols automatic

SYNOPSIS

use Data::TableAutoSum;

my $table = Data::TableAutoSum->new(rows => 10, cols => 20); 
# or
my $table = Data::TableAutoSum->new(rows => ['New York', 'L.A.', 'Chicago'],
                                    cols => ['Women', 'Men', 'Alien']);

foreach my $row ($table->rows()) {
   foreach my $col ($table->cols()) {
      $table->data($row,$col) = rand();
      $table->data($row,$col) += $table->data($row-1,$col-1) 
          if $row >= 1 && $col >= 1;
   }
}

$table->change(sub {$_ = int ($_ / 10)}); # World War III perhaps

print "Row $_ has result: ",$table->rowresult($_) for $table->rows();
print "Col $_ has result: ",$table->colresult($_) for $table->cols();
print "Table has the total result: ",$table->totalresult();

print "Let's have a look to the whole table:\n", $table->as_string;

$table->store('random.dat');
my $old_random_data = Data::TableAutoSum->read('random.dat');

# or thinking, we have generated a 
# table for the population( [cities], [centre, suburb] )
# and a similar table with the crimes( [cities], [centre, suburb] )
# we can calculate the crimes per citizen with
$crime_rate = Data::TableAutoSum->merge(
  sub {shift() / shift()}, $crimes, $population
);

ABSTRACT

Table object with automatic calculation of the row/column sums.

DESCRIPTION

This module represents a table with automatic calculation of the row/column sums.

FUNCTIONS

new(rows => $nr_of_rows || \@rows, cols => $nr_of_cols || \@cols)

Creates a new, zero filled table. You can define the rows or cols with a ref to an array of the names of the rows/cols. If so, the names have to be unique. If you only give a number, the rows/cols are named (0 .. $nr-1).

data($row,$col,$new_value)

Get/set of data elements in the table. $new_value is optional Note, that the return value is an lvalue, so you can e.g. set a new value via $table->data($row,$col) = 4; or modify all values with

foreach my $row ($table->rows) {
  foreach my $col ($table->cols) {
    $table->data($row,$col) *= 1.05;
  }
}

rows(), cols()

These functions are returning all rows/columns in a list. They are returned in the order as given with the new constructor.

It's not possible to set rows/columns with them.

rowresult($row), colresult($col)

Returns the sum for the specified row/col.

I named the methods *result instead of *sum, as I plan to implement a possibility change the operation, e.g. to max or multiplication.

You can't change the results directly. Change the table data for that.

totalresult()

Returns the sum over all data elements. totalresult is equal to the sum of all rowresults or the sum of all colresults (of course, there could be some rounding errors).

You can't change the result directly. Change the table data for that.

as_string()

Returns a string representation of the table. A typical example could be:

      0     1    2   Sum
0     2     9    4    15
1     7     5    3    15
2     6     1    8    15
Sum  15    15   15    45

The string is a multiline string, the elements of the table are seperated with a tab.

store($filename)

Stores the table in a readable format (the same as used by as_string) into the specified file.

store returns the table object itselfs, so you can use it in the fashion way:

print "Stored the table\n", $table->store($filename)->as_string;

Data::TableAutoSum->read($filename)

Constructs a table found in the filename. It expects a table of the format written by store, what is the same like written with as_string.

I didn't test what happens, using wrong formated files or similar. You're supposed to don't do that.

$table->change(CODE)

Changes every table element with the given code. Note that you have to change $_, so $table-change(sub {$_ *= 2})> doubles every element, while $table-change(sub { 2 * $_ })> doesn't change anything.

$table->merge(CODE, Data::TableAutoSum, Data::TableAutoSum)

Creates a new table, which values depends on the values of two other tables. The value of the cell in row i, column j is calculated with

$new_table->data($i,$j) = $sub->($table1->data($i,$j), $table2->data($i,$j);

Note that both tables have to be of the same dimension. Also the row/column names have to be the same ones.

$table->contains_row($row), $table->contains_col($col)

Does what you would expect.

$table->is_equal($other_table)

Please note, that it is an object method (not a static class method) and you only can compare one table to another table, both of type TableAutoSum.

EXPORT

None by default.

BUGS

The store/read methods are slow. As I wrote the module for convienience, it's not so important for me, but I'll change it a day.

It's not tested what happens when you try to read a misformatted table. Don't do that.

If you work with floating point types, don't expect that $table->store('filename')->read('filename') reproduces exactly the same table, as there could be some rounding errors.

I hope there aren't any more bugs.

TODO

options for as_string, store, read

The seperator, the end of line char, and the "Sum"-string should be changeable.

operation

Possibility to change the internal used operation, at the moment, only '+' is used. I'd like to give the possibility to use any other distributive, associative operation.

overloaded operators

Some operators should be overloaded. I'd like to write something like

my $population_perc = $population / $population->totalresult;
my $euro_prices     = $dm_prices / 1.95883;

my $population = $female_population + $male_population;
my $murders_per_inhabitant = $murders / $inhabitants;

clear/fill

A clear method, that resets all values to 0 and a fill method to fill all elements with a specific value.

subtables

Something like

my $east_alien_population = $population->subtable(rows => ['Chicago', 'New York'],
                                                  cols => 'alien');

Quite an insert_subtable method seems sensful, too.

increase speed of store/read

add_row, add_col, insert_row, insert_col

These functions would be quite convenient.

clone

as_array

It would return the table representation from an array.

REQUIREMENTS

Params::Validate
Regexp::Common
Set::Scalar
List::Util 
Tie::File
Tie::CSV_File
Data::Compare
    
Math::Random            # for the tests
Set::CrossProduct  
Data::Dumper       

Test::More             
Test::Exception    
Test::Builder

SEE ALSO

Data::Xtab, Data::Pivot, Table::Pivoter

AUTHOR

Janek Schleicher, <bigj@kamelfreund.de>

COPYRIGHT AND LICENSE

Copyright 2002 by Janek Schleicher

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