Additional parameter to new()
If you need a single currency of a different type than the others in your program, use this mode:
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:
The locale definition includes two different Currency Symbol strings: one is the native character(s), like $ or X or X; the other is the three character string defined by the ISO4217 specification followed by the normal currency separation character (frequently space). The default behavior is to always display the native CURRENCY_SYMBOL unless a global parameter is set:
$Math::Currency::use_int = 1; # print the currency symbol text
where the INT_CURR_SYMBOL text will used instead.
The included file, scripts/new_currency, will automatically create a new currency formatting subclass, based on your current locale, or any arbitrary locale supported by your operating system. For most unix-like O/Ss, the following command will list the locale files installed:
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 doesnt 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:
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 doesnt 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 formatting can be changed by setting the package global format like this:
In addition to the four predefined formats listed above, you can also use the POSIX monetary format for a locale which you are not currently running (e.g. for a web site). You can set the global monetary format in effect at any time by using:
If you dont want to always have to remember to reinitialize the POSIX settings when you switch locales, you can set the global parameter:
$Math::Currency::always_init = 1;
and every single time a M::C 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 first method of manually updating the global format immediately after you reset the locale.
NOTE: 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.
NOTE 2: 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.
Any object can have its own format different from the current global format, like this:
$pounds = Math::Currency->new(1000, GBP); $dollars = Math::Currency->new(1000); # inherits default US format $dollars->format( USD ); # explicit object format
The format must contains all of the commonly configured LC_MONETARY Locale settings. For example, these are the values of the default US format (with comments):
INT_CURR_SYMBOL => USD, # ISO currency text
CURRENCY_SYMBOL => $, # Local currency character
MON_DECIMAL_POINT => ., # Decimal seperator
MON_THOUSANDS_SEP => ,, # Thousands seperator
MON_GROUPING => 3, # Grouping digits
POSITIVE_SIGN => , # Local positive sign
NEGATIVE_SIGN => -, # Local negative sign
INT_FRAC_DIGITS => 2, # Default Intl. precision
FRAC_DIGITS => 2, # Local precision
P_CS_PRECEDES => 1, # Currency symbol location
P_SEP_BY_SPACE => 0, # Space between Currency and value
N_CS_PRECEDES => 1, # Negative version of above
N_SEP_BY_SPACE => 0, # Negative version of above
P_SIGN_POSN => 1, # Position of positive sign
N_SIGN_POSN => 1, # Position of negative sign
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).
There are times when you would like to take a Math::Currency object and use it with some other module or external agent which doesnt understand the currency formatting.
$m->as_float - bare floating point notation without currency formatting 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, to ensure that you dont have any floating point rounding issues going from/to the database. $m->as_int - bare integer number of minimum value Some US credit card gateways require all transactions to be expressed in pennies (because their software isnt running Math::Currency!). This object method returns an integer value that corresponds to the currency value multiplied by 10 to the power of the number of decimal places of precision. Essentially, this expresses the currency amount in the smallest discrete value allowed with that currency, so for currency expressed in dollars, this method returns the same value in pennies.
Please report any bugs or feature requests to bug-Math-Currency@rt.cpan.org, or through the web interface at <http://rt.cpan.org>.
John Peacock <email@example.com>
Hey! <B>The above document had some coding errors, which are explained below:B>
Around line 579: Non-ASCII character seen before =encoding in X. Assuming ISO8859-1
|perl v5.20.3||MATH::CURRENCY (3)||2016-03-18|