Math::Decimal64 - (alpha) perl interface to C's _Decimal64 operations.
In order to compile this module, a C compiler that provides the _Decimal64 type is needed.
Note that this module is alpha software. It seems to work ok for me on MS Windows (compiling with gcc-4.6.3, gcc-4.7.0) but, at time of release, is untested elsewhere. Math::Decimal64 supports up to 16 decimal digits of significand (mantissa) and an exponent range of -383 to +384. The smallest expressable value is -9.999999999999999e384 (which is also equivalent to -9999999999999999e369). The largest expressable value is 9.999999999999999e384 (which also equivalent to 9999999999999999e369). The closest we can get to zero is (plus or minus) 1e-384 (which is also equivalent to 1000000000000000e-399). This module allows decimal floating point arithmetic via operator overloading - see "OVERLOADING". In the documentation that follows, "$mantissa" is a perl scalar holding a string of up to 16 decimal digits: $mantissa = '1234'; $mantissa = '1234567890123456'; For many values, it normally shouldn't matter if $mantissa is assigned as a number: $mantissa = 1234; # should work ok. But on some perls there are values that *need* to be assigned as a string. For example, on perls where nvtype is an 8 byte 'double': $mantissa = '-9307199254740993'; # works fine $mantissa = -9307199254740993; # will assign wrong value So ... where you see "$mantissa" in the following docs, think *string* of up to 16 decimal digits".
use Math::Decimal64 qw(:all); my $d64_1 = MEtoD64('9927', -2); # the decimal 99.27 my $d64_2 = MEtoD64('3', 0); # the decimal 3.0 $d64_1 /= $d64_2; print $d64_1; # prints 3309e-2 (33.09)
The following operations are overloaded: + - * / += -= *= /= != == <= >= <=> < > ++ -- = abs bool int print Arguments to the overloaded operations must be Math::Decimal64 objects. $d64_2 = $d64_1 + 3.1; # currently an error. Do either: $d64_2 = $d64_1 + MEtoD64('31',-1); # or: $d64_2 = $d64_1 + Math::Decimal64->new('3',0);
The following create and assign a new Math::Decimal64 object. Afaik, MEtoD64 and STRtoD64 will assign the values accurately; the other assignment functions can be subject to rounding errors under certain conditions - use them with caution. ################################### # Assign from mantissa and exponent $d64 = MEtoD64($mantissa, $exponent); eg: $d64 = MEtoD64('12345', -3); # 12.345 Doing Math::Decimal64->new($mantissa, $exponent) will also create and assign using MEtoD64(). ##################################### # Assign from a UV (unsigned integer) $d64 = UVtoD64($uv); eg: $d64 = UVtoD64(~0); Doing Math::Decimal64->new($uv) will also create and assign using UVtoD64(). #################################### # Assign from an IV (signed integer) $d64 = IVtoD64($iv); eg: $d64 = IVtoD64(-15); # -15.0 Doing Math::Decimal64->new($iv) will also create and assign using IVtoD64(). ########################### # Assign from an NV (real)) $d64 = NVtoD64($nv); eg: $d64 = NVtoD64(-3.25); Doing Math::Decimal64->new($nv) will also create and assign using NVtoD64(). ###################### # Assign from a string $d64 = PVtoD64($string); eg: $d64 = PVtoD64('-9427199254740993'); $d64 = PVtoD64('-9307199254740993e-15'); $d64 = Math::Decimal64->new('-9787199254740993'); $d64 = Math::Decimal64->new('-9307199254740993e-23'); Doing Math::Decimal64->new($string) will also create and assign using PVtoD64(). ################################################ # Assign from an existing Math::Decimal64 object $d64 = D64toD64($d64_0); Also: $d64 = Math::Decimal64->new($d64_0); $d64 = $d64_0; # uses overloaded '=' #################### # Assign using new() $d64 = Math::Decimal64->new([$arg1, [$arg2]]); This function calls one of the above functions. It determines the appropriate function to call by examining the argument(s) provided. If no argument is provided, a Math::Decimal64 object with a value of NaN is returned. If 2 arguments are supplied it uses MEtoD64(). If one argument is provided, that arg's flags are used to determine the appropriate function to call. ####################### # Assign using STRtoD64 $d64 = STRtoD64($string); If your C compiler provides the strtod64 function, and you configured the Makefile.PL to enable access to that function then you can use this function. usage is is as for PVtoD64(). ############################## # Assign to an existing object assignME($d64, $mantissa, $exponent); Assigns the value represented by ($mantissa, $exponent) to the Math::Decimal64 object, $d64. eg: assignME($d64, '123459', -6); # 0.123459
$d64 = InfD64($sign); If $sign < 0, returns a Math::Decimal64 object set to negative infinity; else returns a Math::Decimal64 object set to positive infinity. $d64 = NaND64($sign); If $sign < 0, returns a Math::Decimal64 object set to negative NaN; else returns a Math::Decimal64 object set to positive NaN. It may be problematical as to whether a NaN with the correct sign has been returned ... but, either way, it should return a NaN. $d64 = ZeroD64($sign); If $sign < 0, returns a Math::Decimal64 object set to negative zero; else returns a Math::Decimal64 object set to zero.
The following functions provide ways of seeing the value of Math::Decimal64 objects. $nv = D64toNV($d64); This function returns the value of the Math::Decimal64 object to a perl scalar (NV). Under certain conditions it may not translate the value accurately. ($mantissa, $exponent) = D64toME($d64); Returns the value of the Math::Decimal object as a mantissa (string of up to 16 decimal digits) and exponent. You can then manipulate those variables to output the value in your preferred format. Afaik, the value will be translated accurately. print $d64; Will print the value in the format (eg) -12345e-2, which equates to the decimal -123.45. Afaik, the value will be translated accurately.
$d64 = Exp10($pow); Returns a Math::Decimal64 object with a value of 10 ** $pow, for $pow in the range (-398 .. 384). Croaks with appropriate message if $pow is not within that range. $bool = have_strtod64(); Returns true if, when building Math::Decimal64, the Makefile.PL was configured to make the STRtoD64() function available for your build of Math::Decimal64. Else returns false. (No use making this functionc available if your compiler's C library doesn't provide the strtod64 function.) $test = is_ZeroD64($d64); Returns: -1 if $d64 is negative zero; 1 if $d64 is a positive zero; 0 if $d64 is not zero. $test = is_InfD64($d64); Returns: -1 if $d64 is negative infinity; 1 if $d64 is positive infinity; 0 if $d64 is not infinity. $bool = is_NaND64($d64); Returns: 1 if $d64 is a NaN; 0 if $d64 is not a NaN.
This program is free software; you may redistribute it and/or modify it under the same terms as Perl itself. Copyright 2012 Sisyphus
Sisyphus <sisyphus at(@) cpan dot (.) org>
To install Math::Decimal64, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Math::Decimal64
CPAN shell
perl -MCPAN -e shell install Math::Decimal64
For more information on module installation, please visit the detailed CPAN module installation guide.