Ricardo SIGNES > Math-TotalBuilder-1.101 > Math::TotalBuilder

Download:
Math-TotalBuilder-1.101.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 1.101   Source   Latest Release: Math-TotalBuilder-1.102

NAME ^

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

VERSION ^

version 1.101

 $Id: /my/cs/projects/total/trunk/lib/Math/TotalBuilder.pm 27913 2006-11-13T15:50:51.155685Z rjbs  $ 

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.

FUNCTIONS ^

build(\%pieces, $total, \@code)
  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 }

The third, optional, argument to build must be either a coderef or a reference to an array of coderefs, each of which accept \%pieces and $total as arguments. build will return the result of building a total using the passed sub. If an arrayref of coderefs was passed, build will construct a total using each sub and return the total with the smallest remainder.

If no third option is passed, &build_basic, a very simple-minded algorithm, is assumed.

build_basic(\%pieces, $total)

This is the basic algorithm used to build totals. It uses as many of the largest unit will fit, then as many of the next largest, and so on, until it has tried to fit all the units in.

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 isn't exactly 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 ^

AUTHOR ^

Ricardo SIGNES, <rjbs@cpan.org>

COPYRIGHT ^

Copyright (C) 2004, Ricardo SIGNES. This is free software, and can be distributed under the same terms as perl itself.

syntax highlighting: