Ricardo SIGNES 😄

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. If the total can't be cleanly built, the routine will return a set that builds the nearest total it can, without going over. A special value, _remainder will indicate by how many units it fell short.

This module does not solve the knapsack problem, and hardly tries. It may fail to provide a solution for solveable instances, like this:

 my $difficult = build (
   { kroener => 30, talen => 7 },
   49
 ); 
 # yields { kroener => 1, talen => 2, _remainder => 5 }
 # not    { talen => 7 }

Future revisions may grow better.

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?")

  • 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.

  • Provide an option to try harder to build totals.

AUTHOR

Ricardo SIGNES, <rjbs@cpan.org>

COPYRIGHT

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