[p5sagit/p5-mst-13.2.git] / lib / bigint.pm

package bigint;
use 5.006002;

$VERSION = '0.22';
use Exporter;
@ISA		= qw( Exporter );
@EXPORT_OK	= qw( ); 
@EXPORT		= qw( inf NaN ); 

use strict;
use overload;

############################################################################## 

# These are all alike, and thus faked by AUTOLOAD

my @faked = qw/round_mode accuracy precision div_scale/;
use vars qw/$VERSION $AUTOLOAD $_lite/;		# _lite for testsuite

sub AUTOLOAD
  {
  my $name = $AUTOLOAD;

  $name =~ s/.*:://;    # split package
  no strict 'refs';
  foreach my $n (@faked)
    {
    if ($n eq $name)
      {
      *{"bigint::$name"} = sub 
        {
        my $self = shift;
        no strict 'refs';
        if (defined $_[0])
          {
          return Math::BigInt->$name($_[0]);
          }
        return Math::BigInt->$name();
        };
      return &$name;
      }
    }
 
  # delayed load of Carp and avoid recursion
  require Carp;
  Carp::croak ("Can't call bigint\-\>$name, not a valid method");
  }

sub upgrade
  {
  $Math::BigInt::upgrade;
  }

sub _binary_constant
  {
  # this takes a binary/hexadecimal/octal constant string and returns it
  # as string suitable for new. Basically it converts octal to decimal, and
  # passes every thing else unmodified back.
  my $string = shift;

  return Math::BigInt->new($string) if $string =~ /^0[bx]/;

  # so it must be an octal constant
  Math::BigInt->from_oct($string);
  }

sub _float_constant
  {
  # this takes a floating point constant string and returns it truncated to
  # integer. For instance, '4.5' => '4', '1.234e2' => '123' etc
  my $float = shift;

  # some simple cases first
  return $float if ($float =~ /^[+-]?[0-9]+$/);		# '+123','-1','0' etc
  return $float 
    if ($float =~ /^[+-]?[0-9]+\.?[eE]\+?[0-9]+$/);	# 123e2, 123.e+2
  return '0' if ($float =~ /^[+-]?[0]*\.[0-9]+$/);	# .2, 0.2, -.1
  if ($float =~ /^[+-]?[0-9]+\.[0-9]*$/)		# 1., 1.23, -1.2 etc
    {
    $float =~ s/\..*//;
    return $float;
    }
  my ($mis,$miv,$mfv,$es,$ev) = Math::BigInt::_split($float);
  return $float if !defined $mis; 	# doesn't look like a number to me
  my $ec = int($$ev);
  my $sign = $$mis; $sign = '' if $sign eq '+';
  if ($$es eq '-')
    {
    # ignore fraction part entirely
    if ($ec >= length($$miv))			# 123.23E-4
      {
      return '0';
      }
    return $sign . substr ($$miv,0,length($$miv)-$ec);	# 1234.45E-2 = 12
    }
  # xE+y
  if ($ec >= length($$mfv))
    {
    $ec -= length($$mfv);			
    return $sign.$$miv.$$mfv if $ec == 0;	# 123.45E+2 => 12345
    return $sign.$$miv.$$mfv.'E'.$ec; 		# 123.45e+3 => 12345e1
    }
  $mfv = substr($$mfv,0,$ec);
  $sign.$$miv.$mfv; 				# 123.45e+1 => 1234
  }

sub unimport
  {
  $^H{bigint} = undef;					# no longer in effect
  overload::remove_constant('binary','','float','','integer');
  }

sub in_effect
  {
  my $level = shift || 0;
  my $hinthash = (caller($level))[10];
  $hinthash->{bigint};
  }

sub import 
  {
  my $self = shift;

  $^H{bigint} = 1;					# we are in effect

  # some defaults
  my $lib = ''; my $lib_kind = 'try';

  my @import = ( ':constant' );				# drive it w/ constant
  my @a = @_; my $l = scalar @_; my $j = 0;
  my ($ver,$trace);					# version? trace?
  my ($a,$p);						# accuracy, precision
  for ( my $i = 0; $i < $l ; $i++,$j++ )
    {
    if ($_[$i] =~ /^(l|lib|try|only)$/)
      {
      # this causes a different low lib to take care...
      $lib_kind = $1; $lib_kind = 'lib' if $lib_kind eq 'l';
      $lib = $_[$i+1] || '';
      my $s = 2; $s = 1 if @a-$j < 2;	# avoid "can not modify non-existant..."
      splice @a, $j, $s; $j -= $s; $i++;
      }
    elsif ($_[$i] =~ /^(a|accuracy)$/)
      {
      $a = $_[$i+1];
      my $s = 2; $s = 1 if @a-$j < 2;	# avoid "can not modify non-existant..."
      splice @a, $j, $s; $j -= $s; $i++;
      }
    elsif ($_[$i] =~ /^(p|precision)$/)
      {
      $p = $_[$i+1];
      my $s = 2; $s = 1 if @a-$j < 2;	# avoid "can not modify non-existant..."
      splice @a, $j, $s; $j -= $s; $i++;
      }
    elsif ($_[$i] =~ /^(v|version)$/)
      {
      $ver = 1;
      splice @a, $j, 1; $j --;
      }
    elsif ($_[$i] =~ /^(t|trace)$/)
      {
      $trace = 1;
      splice @a, $j, 1; $j --;
      }
    else { die "unknown option $_[$i]"; }
    }
  my $class;
  $_lite = 0;					# using M::BI::L ?
  if ($trace)
    {
    require Math::BigInt::Trace; $class = 'Math::BigInt::Trace';
    }
  else
    {
    # see if we can find Math::BigInt::Lite
    if (!defined $a && !defined $p)		# rounding won't work to well
      {
      eval 'require Math::BigInt::Lite;';
      if ($@ eq '')
        {
        @import = ( );				# :constant in Lite, not MBI
        Math::BigInt::Lite->import( ':constant' );
        $_lite= 1;				# signal okay
        }
      }
    require Math::BigInt if $_lite == 0;	# not already loaded?
    $class = 'Math::BigInt';			# regardless of MBIL or not
    }
  push @import, $lib_kind => $lib if $lib ne '';
  # Math::BigInt::Trace or plain Math::BigInt
  $class->import(@import);

  bigint->accuracy($a) if defined $a;
  bigint->precision($p) if defined $p;
  if ($ver)
    {
    print "bigint\t\t\t v$VERSION\n";
    print "Math::BigInt::Lite\t v$Math::BigInt::Lite::VERSION\n" if $_lite;
    print "Math::BigInt\t\t v$Math::BigInt::VERSION";
    my $config = Math::BigInt->config();
    print " lib => $config->{lib} v$config->{lib_version}\n";
    exit;
    }
  # we take care of floating point constants, since BigFloat isn't available
  # and BigInt doesn't like them:
  overload::constant float => sub { Math::BigInt->new( _float_constant(shift) ); };
  # Take care of octal/hexadecimal constants
  overload::constant binary => sub { _binary_constant(shift) };

  # if another big* was already loaded:
  my ($package) = caller();

  no strict 'refs';
  if (!defined *{"${package}::inf"})
    {
    $self->export_to_level(1,$self,@a);           # export inf and NaN
    }
  }

sub inf () { Math::BigInt->binf(); }
sub NaN () { Math::BigInt->bnan(); }

1;

__END__

=head1 NAME

bigint - Transparent BigInteger support for Perl

=head1 SYNOPSIS

  use bigint;

  $x = 2 + 4.5,"\n";			# BigInt 6
  print 2 ** 512,"\n";			# really is what you think it is
  print inf + 42,"\n";			# inf
  print NaN * 7,"\n";			# NaN

  {
    no bigint;
    print 2 ** 256,"\n";		# a normal Perl scalar now
  }

=head1 DESCRIPTION

All operators (including basic math operations) are overloaded. Integer
constants are created as proper BigInts.

Floating point constants are truncated to integer. All results are also
truncated.

=head2 Options

bigint recognizes some options that can be passed while loading it via use.
The options can (currently) be either a single letter form, or the long form.
The following options exist:

=over 2

=item a or accuracy

This sets the accuracy for all math operations. The argument must be greater
than or equal to zero. See Math::BigInt's bround() function for details.

	perl -Mbigint=a,2 -le 'print 12345+1'

Note that setting precision and accurary at the same time is not possible.

=item p or precision

This sets the precision for all math operations. The argument can be any
integer. Negative values mean a fixed number of digits after the dot, and
are <B>ignored</B> since all operations happen in integer space.
A positive value rounds to this digit left from the dot. 0 or 1 mean round to
integer and are ignore like negative values.

See Math::BigInt's bfround() function for details.

	perl -Mbignum=p,5 -le 'print 123456789+123'

Note that setting precision and accurary at the same time is not possible.

=item t or trace

This enables a trace mode and is primarily for debugging bigint or
Math::BigInt.

=item l, lib, try or only

Load a different math lib, see L<Math Library>.

	perl -Mbigint=lib,GMP -e 'print 2 ** 512'
	perl -Mbigint=try,GMP -e 'print 2 ** 512'
	perl -Mbigint=only,GMP -e 'print 2 ** 512'

Currently there is no way to specify more than one library on the command
line. This means the following does not work:

	perl -Mbignum=l,GMP,Pari -e 'print 2 ** 512'

This will be hopefully fixed soon ;)

=item v or version

This prints out the name and version of all modules used and then exits.

	perl -Mbigint=v

=back

=head2 Math Library

Math with the numbers is done (by default) by a module called
Math::BigInt::Calc. This is equivalent to saying:

	use bigint lib => 'Calc';

You can change this by using:

	use bignum lib => 'GMP';

The following would first try to find Math::BigInt::Foo, then
Math::BigInt::Bar, and when this also fails, revert to Math::BigInt::Calc:

	use bigint lib => 'Foo,Math::BigInt::Bar';

Using C<lib> warns if none of the specified libraries can be found and
L<Math::BigInt> did fall back to one of the default libraries.
To supress this warning, use C<try> instead:

        use bignum try => 'GMP';

If you want the code to die instead of falling back, use C<only> instead:

        use bignum only => 'GMP';

Please see respective module documentation for further details.

=head2 Internal Format

The numbers are stored as objects, and their internals might change at anytime,
especially between math operations. The objects also might belong to different
classes, like Math::BigInt, or Math::BigInt::Lite. Mixing them together, even
with normal scalars is not extraordinary, but normal and expected.

You should not depend on the internal format, all accesses must go through
accessor methods. E.g. looking at $x->{sign} is not a good idea since there
is no guaranty that the object in question has such a hash key, nor is a hash
underneath at all.

=head2 Sign

The sign is either '+', '-', 'NaN', '+inf' or '-inf'.
You can access it with the sign() method.

A sign of 'NaN' is used to represent the result when input arguments are not
numbers or as a result of 0/0. '+inf' and '-inf' represent plus respectively
minus infinity. You will get '+inf' when dividing a positive number by 0, and
'-inf' when dividing any negative number by 0.

=head2 Methods

Since all numbers are now objects, you can use all functions that are part of
the BigInt API. You can only use the bxxx() notation, and not the fxxx()
notation, though. 

=over 2

=item inf()

A shortcut to return Math::BigInt->binf(). Useful because Perl does not always
handle bareword C<inf> properly.

=item NaN()

A shortcut to return Math::BigInt->bnan(). Useful because Perl does not always
handle bareword C<NaN> properly.

=item upgrade()

Return the class that numbers are upgraded to, is in fact returning
C<$Math::BigInt::upgrade>.

=item in_effect()

	use bigint;

	print "in effect\n" if bigint::in_effect;	# true
	{
	  no bigint;
	  print "in effect\n" if bigint::in_effect;	# false
	}

Returns true or false if C<bigint> is in effect in the current scope.

This method only works on Perl v5.9.4 or later.

=back

=head2 MATH LIBRARY

Math with the numbers is done (by default) by a module called

=head2 Caveat

But a warning is in order. When using the following to make a copy of a number,
only a shallow copy will be made.

	$x = 9; $y = $x;
	$x = $y = 7;

Using the copy or the original with overloaded math is okay, e.g. the
following work:

	$x = 9; $y = $x;
	print $x + 1, " ", $y,"\n";	# prints 10 9

but calling any method that modifies the number directly will result in
B<both> the original and the copy being destroyed:
	
	$x = 9; $y = $x;
	print $x->badd(1), " ", $y,"\n";	# prints 10 10
	
        $x = 9; $y = $x;
	print $x->binc(1), " ", $y,"\n";	# prints 10 10
        
	$x = 9; $y = $x;
	print $x->bmul(2), " ", $y,"\n";	# prints 18 18
	
Using methods that do not modify, but testthe contents works:

	$x = 9; $y = $x;
	$z = 9 if $x->is_zero();		# works fine

See the documentation about the copy constructor and C<=> in overload, as
well as the documentation in BigInt for further details.

=head1 MODULES USED

C<bigint> is just a thin wrapper around various modules of the Math::BigInt
family. Think of it as the head of the family, who runs the shop, and orders
the others to do the work.

The following modules are currently used by bigint:

	Math::BigInt::Lite	(for speed, and only if it is loadable)
	Math::BigInt

=head1 EXAMPLES

Some cool command line examples to impress the Python crowd ;) You might want
to compare them to the results under -Mbignum or -Mbigrat:
 
	perl -Mbigint -le 'print sqrt(33)'
	perl -Mbigint -le 'print 2*255'
	perl -Mbigint -le 'print 4.5+2*255'
	perl -Mbigint -le 'print 3/7 + 5/7 + 8/3'
	perl -Mbigint -le 'print 123->is_odd()'
	perl -Mbigint -le 'print log(2)'
	perl -Mbigint -le 'print 2 ** 0.5'
	perl -Mbigint=a,65 -le 'print 2 ** 0.2'
	perl -Mbignum=a,65,l,GMP -le 'print 7 ** 7777'

=head1 LICENSE

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

=head1 SEE ALSO

Especially L<bigrat> as in C<perl -Mbigrat -le 'print 1/3+1/4'> and
L<bignum> as in C<perl -Mbignum -le 'print sqrt(2)'>.

L<Math::BigInt>, L<Math::BigRat> and L<Math::Big> as well
as L<Math::BigInt::BitVect>, L<Math::BigInt::Pari> and  L<Math::BigInt::GMP>.

=head1 AUTHORS

(C) by Tels L<http://bloodgate.com/> in early 2002 - 2007.

=cut
Commit	Line	Data
126f3c5f	1	package bigint;
95a2d02c	2	use 5.006002;
126f3c5f	3
4440d13a	4	$VERSION = '0.22';
126f3c5f	5	use Exporter;
b4bc5691	6	@ISA = qw( Exporter );
	7	@EXPORT_OK = qw( );
	8	@EXPORT = qw( inf NaN );
126f3c5f	9
	10	use strict;
	11	use overload;
	12
	13	##############################################################################
	14
	15	# These are all alike, and thus faked by AUTOLOAD
	16
	17	my @faked = qw/round_mode accuracy precision div_scale/;
	18	use vars qw/$VERSION $AUTOLOAD $_lite/; # _lite for testsuite
	19
	20	sub AUTOLOAD
	21	{
	22	my $name = $AUTOLOAD;
	23
	24	$name =~ s/.*:://; # split package
	25	no strict 'refs';
	26	foreach my $n (@faked)
	27	{
	28	if ($n eq $name)
	29	{
	30	*{"bigint::$name"} = sub
	31	{
	32	my $self = shift;
	33	no strict 'refs';
	34	if (defined $_[0])
	35	{
990fb837	36	return Math::BigInt->$name($_[0]);
126f3c5f	37	}
	38	return Math::BigInt->$name();
	39	};
	40	return &$name;
	41	}
	42	}
	43
	44	# delayed load of Carp and avoid recursion
	45	require Carp;
	46	Carp::croak ("Can't call bigint\-\>$name, not a valid method");
	47	}
	48
	49	sub upgrade
	50	{
95a2d02c	51	$Math::BigInt::upgrade;
126f3c5f	52	}
126f3c5f	53
95a2d02c	54	sub _binary_constant
	55	{
	56	# this takes a binary/hexadecimal/octal constant string and returns it
	57	# as string suitable for new. Basically it converts octal to decimal, and
	58	# passes every thing else unmodified back.
	59	my $string = shift;
	60
	61	return Math::BigInt->new($string) if $string =~ /^0[bx]/;
	62
	63	# so it must be an octal constant
	64	Math::BigInt->from_oct($string);
	65	}
	66
	67	sub _float_constant
126f3c5f	68	{
	69	# this takes a floating point constant string and returns it truncated to
	70	# integer. For instance, '4.5' => '4', '1.234e2' => '123' etc
	71	my $float = shift;
	72
	73	# some simple cases first
	74	return $float if ($float =~ /^[+-]?[0-9]+$/); # '+123','-1','0' etc
	75	return $float
	76	if ($float =~ /^[+-]?[0-9]+\.?[eE]\+?[0-9]+$/); # 123e2, 123.e+2
	77	return '0' if ($float =~ /^[+-]?[0]*\.[0-9]+$/); # .2, 0.2, -.1
	78	if ($float =~ /^[+-]?[0-9]+\.[0-9]*$/) # 1., 1.23, -1.2 etc
	79	{
	80	$float =~ s/\..*//;
	81	return $float;
	82	}
9b924220	83	my ($mis,$miv,$mfv,$es,$ev) = Math::BigInt::_split($float);
126f3c5f	84	return $float if !defined $mis; # doesn't look like a number to me
	85	my $ec = int($$ev);
	86	my $sign = $$mis; $sign = '' if $sign eq '+';
	87	if ($$es eq '-')
	88	{
	89	# ignore fraction part entirely
	90	if ($ec >= length($$miv)) # 123.23E-4
	91	{
	92	return '0';
	93	}
	94	return $sign . substr ($$miv,0,length($$miv)-$ec); # 1234.45E-2 = 12
	95	}
	96	# xE+y
	97	if ($ec >= length($$mfv))
	98	{
	99	$ec -= length($$mfv);
	100	return $sign.$$miv.$$mfv if $ec == 0; # 123.45E+2 => 12345
	101	return $sign.$$miv.$$mfv.'E'.$ec; # 123.45e+3 => 12345e1
	102	}
	103	$mfv = substr($$mfv,0,$ec);
95a2d02c	104	$sign.$$miv.$mfv; # 123.45e+1 => 1234
126f3c5f	105	}
126f3c5f	106
4440d13a	107	sub unimport
	108	{
	109	$^H{bigint} = undef; # no longer in effect
	110	overload::remove_constant('binary','','float','','integer');
	111	}
	112
	113	sub in_effect
	114	{
	115	my $level = shift \|\| 0;
	116	my $hinthash = (caller($level))[10];
	117	$hinthash->{bigint};
	118	}
	119
126f3c5f	120	sub import
	121	{
	122	my $self = shift;
	123
4440d13a	124	$^H{bigint} = 1; # we are in effect
4440d13a	125
126f3c5f	126	# some defaults
bd49aa09	127	my $lib = ''; my $lib_kind = 'try';
126f3c5f	128
	129	my @import = ( ':constant' ); # drive it w/ constant
	130	my @a = @_; my $l = scalar @_; my $j = 0;
	131	my ($ver,$trace); # version? trace?
	132	my ($a,$p); # accuracy, precision
	133	for ( my $i = 0; $i < $l ; $i++,$j++ )
	134	{
bd49aa09	135	if ($_[$i] =~ /^(l\|lib\|try\|only)$/)
126f3c5f	136	{
126f3c5f	137	# this causes a different low lib to take care...
bd49aa09	138	$lib_kind = $1; $lib_kind = 'lib' if $lib_kind eq 'l';
126f3c5f	139	$lib = $_[$i+1] \|\| '';
	140	my $s = 2; $s = 1 if @a-$j < 2; # avoid "can not modify non-existant..."
	141	splice @a, $j, $s; $j -= $s; $i++;
	142	}
	143	elsif ($_[$i] =~ /^(a\|accuracy)$/)
	144	{
	145	$a = $_[$i+1];
	146	my $s = 2; $s = 1 if @a-$j < 2; # avoid "can not modify non-existant..."
	147	splice @a, $j, $s; $j -= $s; $i++;
	148	}
	149	elsif ($_[$i] =~ /^(p\|precision)$/)
	150	{
	151	$p = $_[$i+1];
	152	my $s = 2; $s = 1 if @a-$j < 2; # avoid "can not modify non-existant..."
	153	splice @a, $j, $s; $j -= $s; $i++;
	154	}
	155	elsif ($_[$i] =~ /^(v\|version)$/)
	156	{
	157	$ver = 1;
	158	splice @a, $j, 1; $j --;
	159	}
	160	elsif ($_[$i] =~ /^(t\|trace)$/)
	161	{
	162	$trace = 1;
	163	splice @a, $j, 1; $j --;
	164	}
	165	else { die "unknown option $_[$i]"; }
	166	}
	167	my $class;
	168	$_lite = 0; # using M::BI::L ?
	169	if ($trace)
	170	{
	171	require Math::BigInt::Trace; $class = 'Math::BigInt::Trace';
126f3c5f	172	}
	173	else
	174	{
	175	# see if we can find Math::BigInt::Lite
	176	if (!defined $a && !defined $p) # rounding won't work to well
	177	{
	178	eval 'require Math::BigInt::Lite;';
	179	if ($@ eq '')
	180	{
	181	@import = ( ); # :constant in Lite, not MBI
	182	Math::BigInt::Lite->import( ':constant' );
	183	$_lite= 1; # signal okay
	184	}
	185	}
	186	require Math::BigInt if $_lite == 0; # not already loaded?
	187	$class = 'Math::BigInt'; # regardless of MBIL or not
233f7bc0	188	}
bd49aa09	189	push @import, $lib_kind => $lib if $lib ne '';
126f3c5f	190	# Math::BigInt::Trace or plain Math::BigInt
233f7bc0	191	$class->import(@import);
126f3c5f	192
	193	bigint->accuracy($a) if defined $a;
	194	bigint->precision($p) if defined $p;
	195	if ($ver)
	196	{
	197	print "bigint\t\t\t v$VERSION\n";
	198	print "Math::BigInt::Lite\t v$Math::BigInt::Lite::VERSION\n" if $_lite;
	199	print "Math::BigInt\t\t v$Math::BigInt::VERSION";
	200	my $config = Math::BigInt->config();
	201	print " lib => $config->{lib} v$config->{lib_version}\n";
	202	exit;
	203	}
	204	# we take care of floating point constants, since BigFloat isn't available
	205	# and BigInt doesn't like them:
95a2d02c	206	overload::constant float => sub { Math::BigInt->new( _float_constant(shift) ); };
	207	# Take care of octal/hexadecimal constants
	208	overload::constant binary => sub { _binary_constant(shift) };
b4bc5691	209
4440d13a	210	# if another big* was already loaded:
	211	my ($package) = caller();
	212
	213	no strict 'refs';
	214	if (!defined *{"${package}::inf"})
	215	{
	216	$self->export_to_level(1,$self,@a); # export inf and NaN
	217	}
126f3c5f	218	}
126f3c5f	219
b4bc5691	220	sub inf () { Math::BigInt->binf(); }
	221	sub NaN () { Math::BigInt->bnan(); }
	222
126f3c5f	223	1;
	224
	225	__END__
	226
	227	=head1 NAME
	228
b4bc5691	229	bigint - Transparent BigInteger support for Perl
126f3c5f	230
	231	=head1 SYNOPSIS
	232
f9156151	233	use bigint;
126f3c5f	234
126f3c5f	235	$x = 2 + 4.5,"\n"; # BigInt 6
b4bc5691	236	print 2 ** 512,"\n"; # really is what you think it is
	237	print inf + 42,"\n"; # inf
	238	print NaN * 7,"\n"; # NaN
126f3c5f	239
4440d13a	240	{
	241	no bigint;
	242	print 2 ** 256,"\n"; # a normal Perl scalar now
	243	}
	244
126f3c5f	245	=head1 DESCRIPTION
	246
	247	All operators (including basic math operations) are overloaded. Integer
	248	constants are created as proper BigInts.
	249
	250	Floating point constants are truncated to integer. All results are also
990fb837	251	truncated.
126f3c5f	252
b68b7ab1	253	=head2 Options
126f3c5f	254
	255	bigint recognizes some options that can be passed while loading it via use.
	256	The options can (currently) be either a single letter form, or the long form.
	257	The following options exist:
	258
	259	=over 2
	260
	261	=item a or accuracy
	262
	263	This sets the accuracy for all math operations. The argument must be greater
	264	than or equal to zero. See Math::BigInt's bround() function for details.
	265
	266	perl -Mbigint=a,2 -le 'print 12345+1'
	267
95a2d02c	268	Note that setting precision and accurary at the same time is not possible.
95a2d02c	269
126f3c5f	270	=item p or precision
	271
	272	This sets the precision for all math operations. The argument can be any
	273	integer. Negative values mean a fixed number of digits after the dot, and
	274	are <B>ignored</B> since all operations happen in integer space.
	275	A positive value rounds to this digit left from the dot. 0 or 1 mean round to
	276	integer and are ignore like negative values.
	277
	278	See Math::BigInt's bfround() function for details.
	279
	280	perl -Mbignum=p,5 -le 'print 123456789+123'
	281
95a2d02c	282	Note that setting precision and accurary at the same time is not possible.
95a2d02c	283
126f3c5f	284	=item t or trace
	285
	286	This enables a trace mode and is primarily for debugging bigint or
	287	Math::BigInt.
	288
bd49aa09	289	=item l, lib, try or only
126f3c5f	290
bd49aa09	291	Load a different math lib, see L<Math Library>.
126f3c5f	292
bd49aa09	293	perl -Mbigint=lib,GMP -e 'print 2 ** 512'
	294	perl -Mbigint=try,GMP -e 'print 2 ** 512'
	295	perl -Mbigint=only,GMP -e 'print 2 ** 512'
126f3c5f	296
126f3c5f	297	Currently there is no way to specify more than one library on the command
95a2d02c	298	line. This means the following does not work:
	299
	300	perl -Mbignum=l,GMP,Pari -e 'print 2 ** 512'
	301
	302	This will be hopefully fixed soon ;)
126f3c5f	303
	304	=item v or version
	305
	306	This prints out the name and version of all modules used and then exits.
	307
b68b7ab1	308	perl -Mbigint=v
126f3c5f	309
95a2d02c	310	=back
95a2d02c	311
b68b7ab1	312	=head2 Math Library
126f3c5f	313
	314	Math with the numbers is done (by default) by a module called
	315	Math::BigInt::Calc. This is equivalent to saying:
	316
	317	use bigint lib => 'Calc';
	318
	319	You can change this by using:
	320
bd49aa09	321	use bignum lib => 'GMP';
126f3c5f	322
	323	The following would first try to find Math::BigInt::Foo, then
	324	Math::BigInt::Bar, and when this also fails, revert to Math::BigInt::Calc:
	325
	326	use bigint lib => 'Foo,Math::BigInt::Bar';
	327
bd49aa09	328	Using C<lib> warns if none of the specified libraries can be found and
	329	L<Math::BigInt> did fall back to one of the default libraries.
	330	To supress this warning, use C<try> instead:
	331
	332	use bignum try => 'GMP';
	333
	334	If you want the code to die instead of falling back, use C<only> instead:
	335
	336	use bignum only => 'GMP';
	337
126f3c5f	338	Please see respective module documentation for further details.
126f3c5f	339
b68b7ab1	340	=head2 Internal Format
126f3c5f	341
	342	The numbers are stored as objects, and their internals might change at anytime,
	343	especially between math operations. The objects also might belong to different
	344	classes, like Math::BigInt, or Math::BigInt::Lite. Mixing them together, even
	345	with normal scalars is not extraordinary, but normal and expected.
	346
	347	You should not depend on the internal format, all accesses must go through
990fb837	348	accessor methods. E.g. looking at $x->{sign} is not a good idea since there
126f3c5f	349	is no guaranty that the object in question has such a hash key, nor is a hash
	350	underneath at all.
	351
b68b7ab1	352	=head2 Sign
126f3c5f	353
b68b7ab1	354	The sign is either '+', '-', 'NaN', '+inf' or '-inf'.
126f3c5f	355	You can access it with the sign() method.
	356
	357	A sign of 'NaN' is used to represent the result when input arguments are not
	358	numbers or as a result of 0/0. '+inf' and '-inf' represent plus respectively
	359	minus infinity. You will get '+inf' when dividing a positive number by 0, and
	360	'-inf' when dividing any negative number by 0.
	361
b68b7ab1	362	=head2 Methods
126f3c5f	363
	364	Since all numbers are now objects, you can use all functions that are part of
	365	the BigInt API. You can only use the bxxx() notation, and not the fxxx()
	366	notation, though.
	367
95a2d02c	368	=over 2
	369
	370	=item inf()
	371
	372	A shortcut to return Math::BigInt->binf(). Useful because Perl does not always
	373	handle bareword C<inf> properly.
	374
	375	=item NaN()
	376
	377	A shortcut to return Math::BigInt->bnan(). Useful because Perl does not always
	378	handle bareword C<NaN> properly.
	379
	380	=item upgrade()
	381
	382	Return the class that numbers are upgraded to, is in fact returning
	383	C<$Math::BigInt::upgrade>.
	384
4440d13a	385	=item in_effect()
	386
	387	use bigint;
	388
	389	print "in effect\n" if bigint::in_effect; # true
	390	{
	391	no bigint;
	392	print "in effect\n" if bigint::in_effect; # false
	393	}
	394
	395	Returns true or false if C<bigint> is in effect in the current scope.
	396
	397	This method only works on Perl v5.9.4 or later.
	398
95a2d02c	399	=back
	400
	401	=head2 MATH LIBRARY
	402
	403	Math with the numbers is done (by default) by a module called
	404
b68b7ab1	405	=head2 Caveat
990fb837	406
	407	But a warning is in order. When using the following to make a copy of a number,
	408	only a shallow copy will be made.
	409
	410	$x = 9; $y = $x;
	411	$x = $y = 7;
	412
	413	Using the copy or the original with overloaded math is okay, e.g. the
	414	following work:
	415
	416	$x = 9; $y = $x;
	417	print $x + 1, " ", $y,"\n"; # prints 10 9
	418
	419	but calling any method that modifies the number directly will result in
3c4b39be	420	B<both> the original and the copy being destroyed:
990fb837	421
	422	$x = 9; $y = $x;
	423	print $x->badd(1), " ", $y,"\n"; # prints 10 10
	424
	425	$x = 9; $y = $x;
	426	print $x->binc(1), " ", $y,"\n"; # prints 10 10
	427
	428	$x = 9; $y = $x;
	429	print $x->bmul(2), " ", $y,"\n"; # prints 18 18
	430
	431	Using methods that do not modify, but testthe contents works:
	432
	433	$x = 9; $y = $x;
	434	$z = 9 if $x->is_zero(); # works fine
	435
	436	See the documentation about the copy constructor and C<=> in overload, as
	437	well as the documentation in BigInt for further details.
	438
126f3c5f	439	=head1 MODULES USED
	440
	441	C<bigint> is just a thin wrapper around various modules of the Math::BigInt
	442	family. Think of it as the head of the family, who runs the shop, and orders
	443	the others to do the work.
	444
	445	The following modules are currently used by bigint:
	446
	447	Math::BigInt::Lite (for speed, and only if it is loadable)
	448	Math::BigInt
	449
	450	=head1 EXAMPLES
	451
	452	Some cool command line examples to impress the Python crowd ;) You might want
	453	to compare them to the results under -Mbignum or -Mbigrat:
	454
	455	perl -Mbigint -le 'print sqrt(33)'
	456	perl -Mbigint -le 'print 2*255'
	457	perl -Mbigint -le 'print 4.5+2*255'
	458	perl -Mbigint -le 'print 3/7 + 5/7 + 8/3'
	459	perl -Mbigint -le 'print 123->is_odd()'
	460	perl -Mbigint -le 'print log(2)'
	461	perl -Mbigint -le 'print 2 ** 0.5'
	462	perl -Mbigint=a,65 -le 'print 2 ** 0.2'
95a2d02c	463	perl -Mbignum=a,65,l,GMP -le 'print 7 ** 7777'
126f3c5f	464
	465	=head1 LICENSE
	466
	467	This program is free software; you may redistribute it and/or modify it under
	468	the same terms as Perl itself.
	469
	470	=head1 SEE ALSO
	471
	472	Especially L<bigrat> as in C<perl -Mbigrat -le 'print 1/3+1/4'> and
	473	L<bignum> as in C<perl -Mbignum -le 'print sqrt(2)'>.
	474
	475	L<Math::BigInt>, L<Math::BigRat> and L<Math::Big> as well
	476	as L<Math::BigInt::BitVect>, L<Math::BigInt::Pari> and L<Math::BigInt::GMP>.
	477
	478	=head1 AUTHORS
	479
95a2d02c	480	(C) by Tels L<http://bloodgate.com/> in early 2002 - 2007.
126f3c5f	481
126f3c5f	482	=cut