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.

    148290

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

Copyright 1997, 1998 Evolution Online Systems, Inc.

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