/ 
Math-Decimal64-0.01
River stage zero No dependents
/ Math::Decimal64

NAME

Math::Decimal64 - (alpha) perl interface to C's _Decimal64 operations.

DEPENDENCIES

In order to compile this module, a C compiler that provides
the _Decimal64 type is needed.

DESCRIPTION

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-383
(which is also equivalent to 1000000000000000e-398).

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".

SYNOPSIS

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)

OVERLOADING

The following operations are overloaded:
 + - * /
 += -= *= /=
 != == <= >= <=> < >
 ++ --
 =
 abs bool int print

 Arguments to the overloaded operations must be Math::Decimal64
 objects.

  $d64_2 = $d64_1 + 3.0; # currently an error. Do either:

  $d64_2 = $d64_1 + MEtoD64('3',0); # or:
  $d64_2 = $d64_1 + Math::Decimal64->new('3',0);

ASSIGNMENT FUNCTIONS

The following create and assign a new Math::Decimal64 object.

 # 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().
  Not recommended - especially on perls where nvtype is a
  double.

 # 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.

 $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().

The following function assigns a new value to an already-
existing Math::Decimal64 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

ASSIGNMENT OF INF, NAN and ZERO

$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 
 positive zero.

OTHER FUNCTIONS

$d64 = exp10($pow);
 Returns a Math::Decimal64 object with a value of
 10 ** $pow, for $pow in the range (-398 .. 383). Croaks
 with appropriate message if $pow is not within that range.

$bool = have_strtod64();
 Returns true if the STRtoD64() function is functional for
 your build of Math::Decimal64. Else returns false.

$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.

RETRIEVAL FUNCTIONS

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). It does not always
  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.

 print $d64;
  Will print the value in the format (eg) -12345e-2, which
  equates to the decimal -123.45.

LICENSE

This program is free software; you may redistribute it and/or 
modify it under the same terms as Perl itself.
Copyright 2012 Sisyphus

AUTHOR

Sisyphus <sisyphus at(@) cpan dot (.) org>