The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Math-BigInt-Parts-0.03
River stage zero No dependents
++
/ Math::BigInt::Parts

NAME

Math::BigInt::Parts - split a Math::BigInt into signed mantissa and exponent

SYNOPSIS

  use Math::BigInt::Parts;

  # Planck's constant

  $h = Math::BigFloat -> new('6.6260693e-34');

  # A non-zero, finite mantissa $m always satisfies 1 <= $m < 10:

  ($m, $e) = fparts($h);      # $m = 6.6260693, $e = -34

  # A non-zero, finite mantissa $m always satisfies 1 <= $m < 1000
  # and the exponent $e is always a multiple of 3:

  ($m, $e) = eparts($h);      # $m = 662.60693, $e = -36

  # Compare this to the standard parts method, which returns both
  # the mantissa and exponent as integers:

  ($m, $e) = $h -> parts();   # $m = 66260693, $e = -41

  # The functions can also be used as methods, by importing them
  # into the Math::BigInt namespace:

  {
      package Math::BigInt;
      use Math::BigInt::Parts ':all';
  }

  ($m, $e) = $h -> fparts();
  ($m, $e) = $h -> eparts();

DESCRIPTION

This module implements the Math::BigInt functions fparts() and eparts() which are variants of the standard Math::BigInt method parts(). The functions fparts() and eparts() return the mantissa and exponent with the values that are common for floating point numbers in standard notation and in engineering notation, respectively.

FUNCTIONS

Behaviour common to both functions

The following applies to both functions, and assumes the functions are called using

  ($m, $e) = fparts($x);      # fparts() or eparts()
  $m = fparts($x);            # fparts() or eparts()
Values

For a zero value operand $x, both the mantissa $m and the exponent $e is zero. For plus/minus infinity, the mantissa is a signed infinity and the exponent is plus infinity. For NaN (Not-a-Number), both the mantissa and the exponent is NaN. For a non-zero, finite $x, see the appropriate function below.

Regardless of the operand $x and the function, the returned mantissa $m and the exponent $e give back the value of $x with

  $x = Math::BigFloat -> new(10) -> bpow($e) -> bmul($m);

or the more efficient

  $x = $m -> copy() -> blsft($e, 10);

Note that since $e is a Math::BigInt, the following

  $x = $m * 10 ** $e;

will only give back the value of $x when $e is non-negative.

Context

In list context the mantissa and exponent is returned. In scalar context the mantissa is returned. In void context a warning is given, since there is no point in using any of the functions in a void context.

Classes

The mantissa is always a Math::BigFloat object, and the exponent is always a Math::BigInt object.

Behaviour specific to each function

fparts ()

For a non-zero, finite $x the mantissa $m always satisfies 1 <= $m < 10 and the exponent is an integer.

eparts ()

For a non-zero, finite $x the mantissa $m always satisfies 1 <= $m < 1000 and the exponent is an integer which is a multiple of 3.

BUGS

Please report any bugs or feature requests to bug-math-bigint-parts at rt.cpan.org, or through the web interface at

  L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Math-BigInt-Parts>

I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

  perldoc Math::BigInt::Parts

You can also look for information at:

SEE ALSO

The documentation for Math::BigInt and Math::BigFloat.

AUTHOR

Peter John Acklam, <pjacklam@online.no>

If you have found this module to be useful, I will be happy to hear about it!

COPYRIGHT AND LICENSE

Copyright 2006-2010 by Peter John Acklam <pjacklam@online.no>

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.0 or, at your option, any later version of Perl 5 you may have available.