new

• new()

  Creates a new currency object with value "0".

• new($value)

  Creates a new currency object with the given value. Note that $value should be quoted to avoid locale formatting issues. E.g.: "new('1234.56')".

• new($value, $curency)

  Creates a new currency object in the given locale. See "Predefined Locales".

format($key, $value)

as_float

When storing the value into a database, you often need a string which corresponds to the value of the currency as a floating point number, but without the special currency formatting. That is what this object method produces. Be sure and use e.g. DECIMAL(10,2) in MySQL, or NUMERIC(10,3) in PostgreSQL to ensure that you don't have any floating point rounding issues going from/to the database.

copy

as_int

localize

If you don't want to always have to remember to reinitialize the POSIX settings when you switch locales, see always_init

Examples:

• "Math::Currency->localize()"

  Renitialize the global internal format hash using the current locale

• "Math::Currency->localize(\$format)"

  Renitialize the hashref $format using the current locale.

available_locales

always_init

 Math::Currency->always_init(1);

Alternatively, you can set the global variable:

 $Math::Currency::always_init = 1;

and every single time a Math::Currency object is printed, the global $FORMAT will be updated to the locale current at that time. This may be a performance hit. It would be better if you followed the method of manually updating the global format immediately after you reset the locale.

Notes

• This function will reset only the global format and will not have effect on objects created with their own overridden formats, even if they were originally based on the global format.
• You must have all the locale files in question already loaded; the list reported by "locale -a" is not always a reliable judge of what files you might actually have installed. If you try and set a nonexistant locale, or set the same locale as is already active, the module will silently retain the current locale settings.

use_int

Pass a true value to this to indicate that the international currency symbol ("INT_CURR_SYMBOL") should be used instead of local currency symbol ("CURRENCY_SYMBOL"). Note that this is a global setting for the library and will affect all objects. For example, in the "USD" locale, stringification of 1234.56 looks like:

• use_int(0)

  $1,234.56

• use_int(1)

  USD 1,234.56

Money

Locale Support

The automatic locale support will take effect if you request a locale by name in the for lc_CC (language/country code) like fr_CA (French Canadian) or en_NZ (English New Zealand). If you pregenerate your "Custom Locale", an alias class will be added so that you can refer to the currency by either the locale name or the INT_CURR_SYMBOL (e.g. USD or GBP).

IMPORTANT NOTE: there are multiple locales which implement the EUR (Euro) currency, each with slightly different formatting rules (aren't standards wonderful). If you "use" multiple currencies that represent EUR, the last one loaded will be available as the INT_CURR_SYMBOL shortcut. You should always use the locale name to refer to these currencies, if you are mixing them in a single program.

Predefined Locales

    en_US = United States dollars (the default if no locale)
    en_GB = British Pounds Sterling
    ja_JP = Japanese Yen 
    de_DE = German Euro

These currency formats are implemented using subclasses for easy extension (see "Custom Locales" for details on creating new subclasses for unsupported locales). If you are using a locale in a country that uses the Euro, you should create your own local format file using your default LANG setting, since the Euro formatting rules are country specific.

If you want to use any locale other than your default in a single script, there are two different ways to specify which currency format you wish to use, with somewhat subtle differences:

• Additional parameter to new()

  If you need a single currency of a different type than the others in your program, use this mode:

    use Math::Currency;
    my $dollars = Math::Currency->new("1.23"); # default behavior
    my $euros = Math::Currency->new("1.23", "de_DE"); # different format
      

  The last line above will automatically load the applicable subclass and use that formatting for that specific object. These formats can either use a pre-generated subclass or will automatically generate an automatic "Custom Locale",

• Directly calling the subclass

  If all (or most) of your currency values should be formatted using the same rules, create the objects directly using the subclass:

    use Math::Currency::ja_JP; # Japanese Yen
    my $yen = Math::Currency::JPY->new("1.345"); # compatibility class
    my $yen2 = $yen->new("3.456"); # you can use an existing object
      

Currency Symbol

    $Math::Currency::use_int = 1; # print the currency symbol text

where the INT_CURR_SYMBOL text will used instead.

Custom Locales

    locale -a

and any of those installed locales can [potentially] be used to create a new locale formatting file.

It is not necessary to do this, since using the format command to switch to a locale which doesn't already have a subclass defined for it will attempt to generate a locale format on the fly. However, it should be noted that the automated generation method will merely look for the first locales that uses the requested INT_CURR_SYMBOL. There may be several locales which use that same currency symbol, with subtle differences (this is especially true of the EUR format), so it is best to pre-generate all of the POSIX currency subclasses you expect, based on the locales you wish to support, to utilize when installing this module, instead of relying on the autogeneration methods.

To create a new locale formatting subclass, change to the top level build directory for Math::Currency and run the following command:

    scripts/new_currency [xx_XX]

where xx_XX is the locale name obtained from the `locale -a` command. This will create a new locale subclass in the lib/Math/Currency/ directory, and this file will be installed when `./Build install` is next run.

If you run the script without any commandline option, it will take the contents of your LANG environment variable and generate your default locale. NOTE that if you are using a UTF-8 locale, the generated file will also be UTF-8 (which may not be what you want). You probably always want to specify the locale name when generating new classes.

The new_currency script will function from within the current build directory, and doesn't depend the current version of Math::Currency being already installed, so you can build all of your commonly used locale files and install them at once.

Global Format

    Math::Currency->format('USD');

POSIX Locale Global Formatting

    use POSIX qw( locale_h );
    setlocale(LC_ALL,"en_GB");   # some locale alias
    Math::Currency->localize;    # reinitialize global format

If you don't want to always have to remember to reinitialize the POSIX settings when you switch locales, see always_init

Object Formats

    $pounds  = Math::Currency->new(1000, 'GBP');
    $dollars = Math::Currency->new(1000); # inherits default US format
    $dollars->format( 'USD' ); # explicit object format

Format Parameters

See chart below for how the various sign character and location settings interact.

Each of the formatting parameters can be individually changed at the object or class (global) level; if an object is currently sharing the global format, all the global parameters will be copied prior to setting the overrided parameters. For example:

    $dollars = Math::Currency->new(1000); # inherits default US format
    $dollars->format('CURRENCY_SYMBOL',' Bucks'); # now has its own format
    $dollars->format('P_CS_PRECEDES',0); # now has its own format
    print $dollars; # displays as "1000 Bucks"

Or you can also set individual elements of the current global format:

    Math::Currency->format('CURRENCY_SYMBOL',' Bucks'); # global changed

The [NP]_SIGN_POSN parameter determines how positive and negative signs are displayed. [NP]_CS_PRECEEDS determines where the currency symbol is shown. [NP]_SEP_BY_SPACE determines whether the currency symbol cuddles the value or not. The following table shows the relationship between these three parameters:

                                               p_sep_by_space
                                         0          1          2

 p_cs_precedes = 0   p_sign_posn = 0    (1.25$)    (1.25 $)   (1.25 $)
                     p_sign_posn = 1    +1.25$     +1.25 $    +1.25 $
                     p_sign_posn = 2     1.25$+     1.25 $+    1.25$ +
                     p_sign_posn = 3     1.25+$     1.25 +$    1.25+ $
                     p_sign_posn = 4     1.25$+     1.25 $+    1.25$ +

 p_cs_precedes = 1   p_sign_posn = 0   ($1.25)   ($ 1.25)   ($ 1.25)
                     p_sign_posn = 1   +$1.25    +$ 1.25    + $1.25
                     p_sign_posn = 2    $1.25+    $ 1.25+     $1.25 +
                     p_sign_posn = 3   +$1.25    +$ 1.25    + $1.25
                     p_sign_posn = 4   $+1.25    $+ 1.25    $ +1.25

(the negative variants are similar).