Data::Quantity::Finance::Currency

Currency-appropriate formatting for numbers

Synopsis

  use Data::Quantity::Finance::Currency;
  
  print Data::Quantity::Finance::Currency->type('USD')->readable_value( $pennies );
  
  $pennies = Data::Quantity::Finance::Currency->type('USD')->numeric_value( <STDIN> );

Description

This module provides functions to convert between different representations of currency values. It does not (yet) actually handle any foreign currencies, conversions or multiple-currency environments, but I imagine it might, some day.

Integer values are used for internal representation of currency values to avoid floating-point vagaries. For US Dollars, this means that values are stored as an integer number of pennies.

readable_value

Converts an integer value to a readable string.

For US Dollars, this includes 1 = $0.01> and 148290 = $1,482.90>.

numeric_value

Convert an externally-generated candidate value into an integer.

For US Dollars, this includes 1 = $0.01> and 148290 = $1,482.90>.

There are two internal representations:

storable

An integer value containing the major and minor currency numbers.

split

A list of the major and minor currency numbers; in the context of US currency, these would be the dollar and cent amounts.

    ( 1482, 90 )

Reference

Package Configuration

$CurrencySymbol: The local currency symbol. Defaults to '$'.
$DecimalPlaces: The number of decimal places supported by the selected currency. Defaults to 2.
$DecimalSep: The decimal separator for the selected currency. Defaults to '.'.
$DisplayDecimals: A flag to indicate if decimals are shown in display string. Defaults to 1.

Conversions

display_store( $integer_value ) : $display_str: Converts a value in the integral storage format to a formatted display string.
update_store( $integer_value ) : $decimal_number: Converts a value in the integral storage format to an editable decimal number.
store_update( $decimal_number ) : $integer_value: Converts a value in the editable decimal number format to a storable integer.
display_update( $decimal_number ) : $display_str: Converts a value in the editable decimal number format to a formatted display string.

Split Input

These functions take a value in the storage or update format and convert it to a list of major and minor currency numbers.

split_update( $decimal_number ) : ($major, $minor): Accepts a dollar value (formatted or not) and returns a list of dollars and cents.
split_store( $integer_value ) : ($major, $minor)
conventionalize($major, $minor) : ($major, $minor): Provides appropriate zero-padding for the major and minor currency numbers.

Split Output

store_split($major, $minor) : $integer_value
update_split($major, $minor) : $decimal_number
display_split($major, $minor) : $display_str

Compatibility

pretty_dollars( $decimal_number ) : $display_str

Now invokes display_update.

Returns a value with a dollar sign, comma separated groups and appropriate decimal values.

cents_to_dollars( $integer_value ) : $display_str

Now invokes display_store.

Works as pretty_dollars above, but converts argument from an integer number of pennies.

dollars_to_cents( $decimal_number ) : $integer_value

Now invokes store_update.

Accepts a dollar value and returns an integer ammount of pennies.

pennies( $integer_value ) : $decimal_number

Now invokes update_store.

Caveats and Upcoming Changes

This module is still somewhat disorganized; the interface is likely to change in future versions.

This is Free Software

You can use this software under the same terms as Perl itself.