[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 parts and results of
expressions are also truncated.

Unlike L<integer>, this pragma creates integer constants that are only
limited in their size by the available memory and CPU time.

=head2 use integer vs. use bigint

There is one small difference between C<use integer> and C<use bigint>: the
former will not affect assignments to variables and the return value of
some functions. C<bigint> truncates these results to integer too:

	# perl -Minteger -wle 'print 3.2'
	3.2
	# perl -Minteger -wle 'print 3.2 + 0'
	3
	# perl -Mbigint -wle 'print 3.2'
	3
	# perl -Mbigint -wle 'print 3.2 + 0'
	3

	# perl -Mbigint -wle 'print exp(1) + 0'
	2
	# perl -Mbigint -wle 'print exp(1)'
	2
	# perl -Mbigint -wle 'print exp(1)'
	2.71828182845905
	# perl -Mbigint -wle 'print exp(1) + 0'
	2

In practice this makes seldom a difference as B<parts and results> of
expressions will be truncated anyway, but this can, for instance, affect the
return value of subroutines:

	sub three_integer { use integer; return 3.2; } 
	sub three_bigint { use bigint; return 3.2; }
 
	print three_integer(), " ", three_bigint(),"\n";	# prints "3.2 3"

=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
1ad2138d	250	Floating point constants are truncated to integer. All parts and results of
	251	expressions are also truncated.
	252
	253	Unlike L<integer>, this pragma creates integer constants that are only
	254	limited in their size by the available memory and CPU time.
	255
	256	=head2 use integer vs. use bigint
	257
	258	There is one small difference between C<use integer> and C<use bigint>: the
	259	former will not affect assignments to variables and the return value of
	260	some functions. C<bigint> truncates these results to integer too:
	261
	262	# perl -Minteger -wle 'print 3.2'
	263	3.2
	264	# perl -Minteger -wle 'print 3.2 + 0'
	265	3
	266	# perl -Mbigint -wle 'print 3.2'
	267	3
	268	# perl -Mbigint -wle 'print 3.2 + 0'
	269	3
	270
	271	# perl -Mbigint -wle 'print exp(1) + 0'
	272	2
	273	# perl -Mbigint -wle 'print exp(1)'
	274	2
	275	# perl -Mbigint -wle 'print exp(1)'
	276	2.71828182845905
	277	# perl -Mbigint -wle 'print exp(1) + 0'
	278	2
	279
	280	In practice this makes seldom a difference as B<parts and results> of
	281	expressions will be truncated anyway, but this can, for instance, affect the
	282	return value of subroutines:
	283
	284	sub three_integer { use integer; return 3.2; }
	285	sub three_bigint { use bigint; return 3.2; }
	286
	287	print three_integer(), " ", three_bigint(),"\n"; # prints "3.2 3"
126f3c5f	288
b68b7ab1	289	=head2 Options
126f3c5f	290
	291	bigint recognizes some options that can be passed while loading it via use.
	292	The options can (currently) be either a single letter form, or the long form.
	293	The following options exist:
	294
	295	=over 2
	296
	297	=item a or accuracy
	298
	299	This sets the accuracy for all math operations. The argument must be greater
	300	than or equal to zero. See Math::BigInt's bround() function for details.
	301
	302	perl -Mbigint=a,2 -le 'print 12345+1'
	303
95a2d02c	304	Note that setting precision and accurary at the same time is not possible.
95a2d02c	305
126f3c5f	306	=item p or precision
	307
	308	This sets the precision for all math operations. The argument can be any
	309	integer. Negative values mean a fixed number of digits after the dot, and
	310	are <B>ignored</B> since all operations happen in integer space.
	311	A positive value rounds to this digit left from the dot. 0 or 1 mean round to
	312	integer and are ignore like negative values.
	313
	314	See Math::BigInt's bfround() function for details.
	315
	316	perl -Mbignum=p,5 -le 'print 123456789+123'
	317
95a2d02c	318	Note that setting precision and accurary at the same time is not possible.
95a2d02c	319
126f3c5f	320	=item t or trace
	321
	322	This enables a trace mode and is primarily for debugging bigint or
	323	Math::BigInt.
	324
bd49aa09	325	=item l, lib, try or only
126f3c5f	326
bd49aa09	327	Load a different math lib, see L<Math Library>.
126f3c5f	328
bd49aa09	329	perl -Mbigint=lib,GMP -e 'print 2 ** 512'
	330	perl -Mbigint=try,GMP -e 'print 2 ** 512'
	331	perl -Mbigint=only,GMP -e 'print 2 ** 512'
126f3c5f	332
126f3c5f	333	Currently there is no way to specify more than one library on the command
95a2d02c	334	line. This means the following does not work:
	335
	336	perl -Mbignum=l,GMP,Pari -e 'print 2 ** 512'
	337
	338	This will be hopefully fixed soon ;)
126f3c5f	339
	340	=item v or version
	341
	342	This prints out the name and version of all modules used and then exits.
	343
b68b7ab1	344	perl -Mbigint=v
126f3c5f	345
95a2d02c	346	=back
95a2d02c	347
b68b7ab1	348	=head2 Math Library
126f3c5f	349
	350	Math with the numbers is done (by default) by a module called
	351	Math::BigInt::Calc. This is equivalent to saying:
	352
	353	use bigint lib => 'Calc';
	354
	355	You can change this by using:
	356
bd49aa09	357	use bignum lib => 'GMP';
126f3c5f	358
	359	The following would first try to find Math::BigInt::Foo, then
	360	Math::BigInt::Bar, and when this also fails, revert to Math::BigInt::Calc:
	361
	362	use bigint lib => 'Foo,Math::BigInt::Bar';
	363
bd49aa09	364	Using C<lib> warns if none of the specified libraries can be found and
	365	L<Math::BigInt> did fall back to one of the default libraries.
	366	To supress this warning, use C<try> instead:
	367
	368	use bignum try => 'GMP';
	369
	370	If you want the code to die instead of falling back, use C<only> instead:
	371
	372	use bignum only => 'GMP';
	373
126f3c5f	374	Please see respective module documentation for further details.
126f3c5f	375
b68b7ab1	376	=head2 Internal Format
126f3c5f	377
	378	The numbers are stored as objects, and their internals might change at anytime,
	379	especially between math operations. The objects also might belong to different
	380	classes, like Math::BigInt, or Math::BigInt::Lite. Mixing them together, even
	381	with normal scalars is not extraordinary, but normal and expected.
	382
	383	You should not depend on the internal format, all accesses must go through
990fb837	384	accessor methods. E.g. looking at $x->{sign} is not a good idea since there
126f3c5f	385	is no guaranty that the object in question has such a hash key, nor is a hash
	386	underneath at all.
	387
b68b7ab1	388	=head2 Sign
126f3c5f	389
b68b7ab1	390	The sign is either '+', '-', 'NaN', '+inf' or '-inf'.
126f3c5f	391	You can access it with the sign() method.
	392
	393	A sign of 'NaN' is used to represent the result when input arguments are not
	394	numbers or as a result of 0/0. '+inf' and '-inf' represent plus respectively
	395	minus infinity. You will get '+inf' when dividing a positive number by 0, and
	396	'-inf' when dividing any negative number by 0.
	397
b68b7ab1	398	=head2 Methods
126f3c5f	399
	400	Since all numbers are now objects, you can use all functions that are part of
	401	the BigInt API. You can only use the bxxx() notation, and not the fxxx()
	402	notation, though.
	403
95a2d02c	404	=over 2
	405
	406	=item inf()
	407
	408	A shortcut to return Math::BigInt->binf(). Useful because Perl does not always
	409	handle bareword C<inf> properly.
	410
	411	=item NaN()
	412
	413	A shortcut to return Math::BigInt->bnan(). Useful because Perl does not always
	414	handle bareword C<NaN> properly.
	415
	416	=item upgrade()
	417
	418	Return the class that numbers are upgraded to, is in fact returning
	419	C<$Math::BigInt::upgrade>.
	420
4440d13a	421	=item in_effect()
	422
	423	use bigint;
	424
	425	print "in effect\n" if bigint::in_effect; # true
	426	{
	427	no bigint;
	428	print "in effect\n" if bigint::in_effect; # false
	429	}
	430
	431	Returns true or false if C<bigint> is in effect in the current scope.
	432
	433	This method only works on Perl v5.9.4 or later.
	434
95a2d02c	435	=back
	436
	437	=head2 MATH LIBRARY
	438
	439	Math with the numbers is done (by default) by a module called
	440
b68b7ab1	441	=head2 Caveat
990fb837	442
	443	But a warning is in order. When using the following to make a copy of a number,
	444	only a shallow copy will be made.
	445
	446	$x = 9; $y = $x;
	447	$x = $y = 7;
	448
	449	Using the copy or the original with overloaded math is okay, e.g. the
	450	following work:
	451
	452	$x = 9; $y = $x;
	453	print $x + 1, " ", $y,"\n"; # prints 10 9
	454
	455	but calling any method that modifies the number directly will result in
3c4b39be	456	B<both> the original and the copy being destroyed:
990fb837	457
	458	$x = 9; $y = $x;
	459	print $x->badd(1), " ", $y,"\n"; # prints 10 10
	460
	461	$x = 9; $y = $x;
	462	print $x->binc(1), " ", $y,"\n"; # prints 10 10
	463
	464	$x = 9; $y = $x;
	465	print $x->bmul(2), " ", $y,"\n"; # prints 18 18
	466
	467	Using methods that do not modify, but testthe contents works:
	468
	469	$x = 9; $y = $x;
	470	$z = 9 if $x->is_zero(); # works fine
	471
	472	See the documentation about the copy constructor and C<=> in overload, as
	473	well as the documentation in BigInt for further details.
	474
126f3c5f	475	=head1 MODULES USED
	476
	477	C<bigint> is just a thin wrapper around various modules of the Math::BigInt
	478	family. Think of it as the head of the family, who runs the shop, and orders
	479	the others to do the work.
	480
	481	The following modules are currently used by bigint:
	482
	483	Math::BigInt::Lite (for speed, and only if it is loadable)
	484	Math::BigInt
	485
	486	=head1 EXAMPLES
	487
	488	Some cool command line examples to impress the Python crowd ;) You might want
	489	to compare them to the results under -Mbignum or -Mbigrat:
	490
	491	perl -Mbigint -le 'print sqrt(33)'
	492	perl -Mbigint -le 'print 2*255'
	493	perl -Mbigint -le 'print 4.5+2*255'
	494	perl -Mbigint -le 'print 3/7 + 5/7 + 8/3'
	495	perl -Mbigint -le 'print 123->is_odd()'
	496	perl -Mbigint -le 'print log(2)'
	497	perl -Mbigint -le 'print 2 ** 0.5'
	498	perl -Mbigint=a,65 -le 'print 2 ** 0.2'
95a2d02c	499	perl -Mbignum=a,65,l,GMP -le 'print 7 ** 7777'
126f3c5f	500
	501	=head1 LICENSE
	502
	503	This program is free software; you may redistribute it and/or modify it under
	504	the same terms as Perl itself.
	505
	506	=head1 SEE ALSO
	507
	508	Especially L<bigrat> as in C<perl -Mbigrat -le 'print 1/3+1/4'> and
	509	L<bignum> as in C<perl -Mbignum -le 'print sqrt(2)'>.
	510
	511	L<Math::BigInt>, L<Math::BigRat> and L<Math::Big> as well
	512	as L<Math::BigInt::BitVect>, L<Math::BigInt::Pari> and L<Math::BigInt::GMP>.
	513
	514	=head1 AUTHORS
	515
95a2d02c	516	(C) by Tels L<http://bloodgate.com/> in early 2002 - 2007.
126f3c5f	517
126f3c5f	518	=cut