NAME

Math::TotalBuilder -- build a whole total out of valued pieces

SYNOPSIS

 use Math::TotalBuilder;

 my %lsd = ( pound => 240, shilling => 20, penny => 1 );

 # units for 952 pence
 my %tender = build(\%lsd, 952);

 # total value of 3, 21, 98
 my $wealth = total(\%lsd, { pound => 3, shilling => 21, penny => 98 });

 # best better representation of 18, 6, 40
 my %moolah = build(\%lsd,
   total (\%lsd, { pound => 18, shilling => 6, penny => 40 }));

DESCRIPTION

This module provides two subroutines, build and total, which can be used to handle quantities of valued items. These can be used to build the proper tender to represent a quantity of money, to compose a mass from standard weights, to convert a difference of seconds to a set of time units, or other similar calculations.

Subroutines

build(\%pieces, $total)

  my %nicetime = build (
    { days => 86400, hours => 3600, minutes => 60, seconds => 1 },
        39102
  );

This routine takes a hash of valued units and a total, and it returns the quantity of each unit required to build that total.

total(\%pieces, \%set)

 my $total = total(
   { ten => 10, five => 5, one => 1 },
   { ten =>  2, five => 6 }
 ); # returns 50

This routines returns the total value of the units in %set, valued according to the definition in %pieces.

NOTES

This module is hardly ready for use. It needs much more error-handling. The sub names may be changed in the future to avoid conflict, since they're very simple names, but probably not. (If so, the current names will remain exportable.)

TODO

• Use subrefs for ever-extending pieces. (e.g., "powers of two")

• Allow building a total from a given set of source units. ("I have this many units to try and build into this total. Can I?")

• Catch all the trivial error cases: total can't be built, invalid units in set to total, etc.

• Allow for useful handling of pieces-sets with multiple pieces of the same value: always use one, randomly distribute, etc.

• Allow use of bigfloats so that the smallest value need not be the base value.

• Collect common units into a module.

AUTHOR

Ricardo SIGNES, <rjbs@cpan.org>

COPYRIGHT

This is free software, and can be distributed under the same terms as perl itself.