/ 
Money-ChangeMaker-0.3.1
River stage zero No dependents
/ Money::ChangeMaker

NAME

Money::ChangeMaker - A module to make change based on a monetary quantity.

SYNOPSIS

use Money::ChangeMaker;
use strict;

my($till) = new Money::ChangeMaker;
$till->denominations($till->get_preset('USA'));
# Change for 11 dollars, 38 cents from a 20 dollar bill
print scalar $till->make_change(1138, 2000);
# Prints:
# 1 five dollar bill, 3 dollar bills, 2 quarters, 1 dime and 2 pennies

DESCRIPTION

Money::ChangeMaker represents, roughly, a cash register and the process of giving change for a purchase. As of this release, it only really implements the change-making process, but future releases will implement more of the "cash register" functionality.

METHODS

new() =item new(\%options)

This is the constructor method for the class. You may optionally pass it a hash reference with a set of option => value pairs. The only option available is 'denominations' which takes a reference to an array of Money::ChangeMaker::Denomination objects, which will define the currency set which this object will use.

denominations() =item denominations(@denoms)

Takes one argument, which is optional. If present, it must be a reference to a list of Money::ChangeMaker::Denomination objects -- these objects will define the currency set that this object will use. The list need not be in any particular order. After setting the new value (if an argument was provided), the current value will be returned.

make_change($price, $tendered)

This method requires 2 arguments -- the price of the "item", and the amount of money that was tendered. It will then calculate the numbers and types of monetary units that will be returned as change. The two arguments must be numeric, and they should be properly scaled to the base of the Denomination set you are using. For example, the default currency set is American money, which defines the base unit as one cent, not one dollar. So, to find change for $15.21 out of $20.00, you would call $till->make_change(1521, 2000).

Each denomination set should define its own base unit, and all of the built-in sets in this module use the lowest possible base unit in order to avoid rounding errors with floating point values.

In list context, this method returns a list of denomination objects representing the monetary units to be returned in change, in descending value-order. If more than one of a given type of unit must be returned in the change, that type of object will show up that many times in the returned list.

For example, when getting change for $15.21 from $20.00, the resulting list will have 11 elements, consisting of 4 dollar bill objects, 3 quarter objects and 4 penny objects.

In scalar context, the results as just described are passed to the as_string method before being returned. See that method for more information.

get_preset_names()

Returns a list of the available preset currency groups. This method may be called as either an object or a class method.

get_preset($name)

Returns a reference to a list of Denomination objects, suitable for passing to the 'denominations' method. This mehod may be called as either an object or a class method.

as_string(@denoms)

Accepts a list of Denomination objects, as returned by make_change(), and returns a human-readable description of the change as a string. This mehod may be called as either an object or a class method.

Future Work

  • Support for limited amounts of certain types of currency, i.e. "I have only 2 dimes left"

  • Support for "weighting" the preference of using a certain type of monetary units, i.e. "I am really low on dimes, use nickels instead".

  • Add a "shell" interface, a la CPAN.pm.

  • Add more Denomination presets. Please consider submitting a preset currency set -- see the perldoc for Money::ChangeMaker::Presets for information on submitting them to me.

AUTHOR

Copyright 2007 Avi Finkel <avi@finkel.org>

This package is free software and is provided "as is" without express or implied warranty. It may be used, redistributed and/or modified under the terms of the Perl Artistic License (see http://www.perl.com/perl/misc/Artistic.html)