[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( PI e ); 
@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};
  }

#############################################################################
# the following two routines are for "use bigint qw/hex oct/;":

sub _hex_global
  {
  my $i = $_[0];
  $i = '0x'.$i unless $i =~ /^0x/;
  Math::BigInt->new($i);
  }

sub _oct_global
  {
  my $i = $_[0];
  return Math::BigInt->from_oct($i) if $i =~ /^0[0-7]/;
  Math::BigInt->new($i);
  }

#############################################################################
# the following two routines are for Perl 5.9.4 or later and are lexical

sub _hex
  {
  return CORE::hex($_[0]) unless in_effect(1);
  my $i = $_[0];
  $i = '0x'.$i unless $i =~ /^0x/;
  Math::BigInt->new($i);
  }

sub _oct
  {
  return CORE::oct($_[0]) unless in_effect(1);
  my $i = $_[0];
  return Math::BigInt->from_oct($i) if $i =~ /^0[0-7]/;
  Math::BigInt->new($i);
  }

sub import 
  {
  my $self = shift;

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

  my ($hex,$oct);
  # for newer Perls always override hex() and oct() with a lexical version:
  if ($] > 5.009004)
    {
    $oct = \&_oct;
    $hex = \&_hex;
    }
  # 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 --;
      }
    elsif ($_[$i] eq 'hex')
      {
      splice @a, $j, 1; $j --;
      $hex = \&_hex_global;
      }
    elsif ($_[$i] eq 'oct')
      {
      splice @a, $j, 1; $j --;
      $oct = \&_oct_global;
      }
    elsif ($_[$i] !~ /^(PI|e)\z/)
      {
      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, e and PI
    }
  {
    no warnings 'redefine';
    *CORE::GLOBAL::oct = $oct if $oct;
    *CORE::GLOBAL::hex = $hex if $hex;
  }
  }

sub inf () { Math::BigInt::binf(); }
sub NaN () { Math::BigInt::bnan(); }
sub PI { Math::BigInt->new(3); }
sub e  { Math::BigInt->new(2); }

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
  print hex("0x1234567890123490"),"\n";	# Perl v5.9.4 or later

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

  # Note that this will be global:
  use bigint qw/hex oct/;
  print hex("0x1234567890123490"),"\n";
  print oct("01234567890123490"),"\n";

=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 -Minteger -wle 'print exp(1)'
	2.71828182845905
	# perl -Minteger -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 hex

Override the build-in hex() method with a version that can handle big
integers. Note that under Perl v5.9.4 or ealier, this will be global
and cannot be disabled with "no bigint;".

=item oct

Override the build-in oct() method with a version that can handle big
integers. Note that under Perl v5.9.4 or ealier, this will be global
and cannot be disabled with "no 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 e()

Returns Euler's number C<e>, aka exp(1), to the given number of digits.

=item PI()

Returns PI to the given number of digits.

=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 CAVAETS

=over 2

=item in_effect()

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

=item hex()/oct()

C<bigint> overrides these routines with versions that can also handle
big integer values. Under Perl prior to version v5.9.4, however, this
will not happen unless you specifically ask for it with the two
import tags "hex" and "oct" - and then it will be global and cannot be
disabled inside a scope with "no bigint":

	use bigint qw/hex oct/;

	print hex("0x1234567890123456");
	{
		no bigint;
		print hex("0x1234567890123456");
	}

The second call to hex() will warn about a non-portable constant.

Compare this to:

	use bigint;

	# will warn only under Perl older than v5.9.4
	print hex("0x1234567890123456");

=back

=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 );
fade31f0	7	@EXPORT_OK = qw( PI e );
b4bc5691	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
d1a15766	120	#############################################################################
	121	# the following two routines are for "use bigint qw/hex oct/;":
	122
	123	sub _hex_global
	124	{
	125	my $i = $_[0];
	126	$i = '0x'.$i unless $i =~ /^0x/;
	127	Math::BigInt->new($i);
	128	}
	129
	130	sub _oct_global
	131	{
	132	my $i = $_[0];
	133	return Math::BigInt->from_oct($i) if $i =~ /^0[0-7]/;
	134	Math::BigInt->new($i);
	135	}
	136
	137	#############################################################################
	138	# the following two routines are for Perl 5.9.4 or later and are lexical
	139
	140	sub _hex
	141	{
	142	return CORE::hex($_[0]) unless in_effect(1);
	143	my $i = $_[0];
	144	$i = '0x'.$i unless $i =~ /^0x/;
	145	Math::BigInt->new($i);
	146	}
	147
	148	sub _oct
	149	{
	150	return CORE::oct($_[0]) unless in_effect(1);
	151	my $i = $_[0];
	152	return Math::BigInt->from_oct($i) if $i =~ /^0[0-7]/;
	153	Math::BigInt->new($i);
	154	}
	155
126f3c5f	156	sub import
	157	{
	158	my $self = shift;
	159
4440d13a	160	$^H{bigint} = 1; # we are in effect
4440d13a	161
075d4edd	162	my ($hex,$oct);
d1a15766	163	# for newer Perls always override hex() and oct() with a lexical version:
	164	if ($] > 5.009004)
	165	{
075d4edd	166	$oct = \&_oct;
075d4edd	167	$hex = \&_hex;
d1a15766	168	}
126f3c5f	169	# some defaults
bd49aa09	170	my $lib = ''; my $lib_kind = 'try';
126f3c5f	171
	172	my @import = ( ':constant' ); # drive it w/ constant
	173	my @a = @_; my $l = scalar @_; my $j = 0;
	174	my ($ver,$trace); # version? trace?
	175	my ($a,$p); # accuracy, precision
	176	for ( my $i = 0; $i < $l ; $i++,$j++ )
	177	{
bd49aa09	178	if ($_[$i] =~ /^(l\|lib\|try\|only)$/)
126f3c5f	179	{
126f3c5f	180	# this causes a different low lib to take care...
bd49aa09	181	$lib_kind = $1; $lib_kind = 'lib' if $lib_kind eq 'l';
126f3c5f	182	$lib = $_[$i+1] \|\| '';
	183	my $s = 2; $s = 1 if @a-$j < 2; # avoid "can not modify non-existant..."
	184	splice @a, $j, $s; $j -= $s; $i++;
	185	}
	186	elsif ($_[$i] =~ /^(a\|accuracy)$/)
	187	{
	188	$a = $_[$i+1];
	189	my $s = 2; $s = 1 if @a-$j < 2; # avoid "can not modify non-existant..."
	190	splice @a, $j, $s; $j -= $s; $i++;
	191	}
	192	elsif ($_[$i] =~ /^(p\|precision)$/)
	193	{
	194	$p = $_[$i+1];
	195	my $s = 2; $s = 1 if @a-$j < 2; # avoid "can not modify non-existant..."
	196	splice @a, $j, $s; $j -= $s; $i++;
	197	}
	198	elsif ($_[$i] =~ /^(v\|version)$/)
	199	{
	200	$ver = 1;
	201	splice @a, $j, 1; $j --;
	202	}
	203	elsif ($_[$i] =~ /^(t\|trace)$/)
	204	{
	205	$trace = 1;
	206	splice @a, $j, 1; $j --;
	207	}
d1a15766	208	elsif ($_[$i] eq 'hex')
	209	{
	210	splice @a, $j, 1; $j --;
075d4edd	211	$hex = \&_hex_global;
d1a15766	212	}
	213	elsif ($_[$i] eq 'oct')
	214	{
	215	splice @a, $j, 1; $j --;
075d4edd	216	$oct = \&_oct_global;
d1a15766	217	}
fade31f0	218	elsif ($_[$i] !~ /^(PI\|e)\z/)
	219	{
	220	die ("unknown option $_[$i]");
	221	}
126f3c5f	222	}
	223	my $class;
	224	$_lite = 0; # using M::BI::L ?
	225	if ($trace)
	226	{
	227	require Math::BigInt::Trace; $class = 'Math::BigInt::Trace';
126f3c5f	228	}
	229	else
	230	{
	231	# see if we can find Math::BigInt::Lite
	232	if (!defined $a && !defined $p) # rounding won't work to well
	233	{
	234	eval 'require Math::BigInt::Lite;';
	235	if ($@ eq '')
	236	{
	237	@import = ( ); # :constant in Lite, not MBI
	238	Math::BigInt::Lite->import( ':constant' );
	239	$_lite= 1; # signal okay
	240	}
	241	}
	242	require Math::BigInt if $_lite == 0; # not already loaded?
	243	$class = 'Math::BigInt'; # regardless of MBIL or not
233f7bc0	244	}
bd49aa09	245	push @import, $lib_kind => $lib if $lib ne '';
126f3c5f	246	# Math::BigInt::Trace or plain Math::BigInt
233f7bc0	247	$class->import(@import);
126f3c5f	248
	249	bigint->accuracy($a) if defined $a;
	250	bigint->precision($p) if defined $p;
	251	if ($ver)
	252	{
	253	print "bigint\t\t\t v$VERSION\n";
	254	print "Math::BigInt::Lite\t v$Math::BigInt::Lite::VERSION\n" if $_lite;
	255	print "Math::BigInt\t\t v$Math::BigInt::VERSION";
	256	my $config = Math::BigInt->config();
	257	print " lib => $config->{lib} v$config->{lib_version}\n";
	258	exit;
	259	}
	260	# we take care of floating point constants, since BigFloat isn't available
	261	# and BigInt doesn't like them:
95a2d02c	262	overload::constant float => sub { Math::BigInt->new( _float_constant(shift) ); };
	263	# Take care of octal/hexadecimal constants
	264	overload::constant binary => sub { _binary_constant(shift) };
b4bc5691	265
4440d13a	266	# if another big* was already loaded:
	267	my ($package) = caller();
	268
	269	no strict 'refs';
	270	if (!defined *{"${package}::inf"})
	271	{
fade31f0	272	$self->export_to_level(1,$self,@a); # export inf and NaN, e and PI
4440d13a	273	}
075d4edd	274	{
	275	no warnings 'redefine';
	276	*CORE::GLOBAL::oct = $oct if $oct;
	277	*CORE::GLOBAL::hex = $hex if $hex;
	278	}
126f3c5f	279	}
126f3c5f	280
fade31f0	281	sub inf () { Math::BigInt::binf(); }
fade31f0	282	sub NaN () { Math::BigInt::bnan(); }
13201e38	283	sub PI { Math::BigInt->new(3); }
13201e38	284	sub e { Math::BigInt->new(2); }
b4bc5691	285
126f3c5f	286	1;
	287
	288	__END__
	289
	290	=head1 NAME
	291
b4bc5691	292	bigint - Transparent BigInteger support for Perl
126f3c5f	293
	294	=head1 SYNOPSIS
	295
f9156151	296	use bigint;
126f3c5f	297
126f3c5f	298	$x = 2 + 4.5,"\n"; # BigInt 6
b4bc5691	299	print 2 ** 512,"\n"; # really is what you think it is
	300	print inf + 42,"\n"; # inf
	301	print NaN * 7,"\n"; # NaN
d1a15766	302	print hex("0x1234567890123490"),"\n"; # Perl v5.9.4 or later
126f3c5f	303
4440d13a	304	{
	305	no bigint;
	306	print 2 ** 256,"\n"; # a normal Perl scalar now
	307	}
	308
d1a15766	309	# Note that this will be global:
	310	use bigint qw/hex oct/;
	311	print hex("0x1234567890123490"),"\n";
	312	print oct("01234567890123490"),"\n";
	313
126f3c5f	314	=head1 DESCRIPTION
	315
	316	All operators (including basic math operations) are overloaded. Integer
	317	constants are created as proper BigInts.
	318
1ad2138d	319	Floating point constants are truncated to integer. All parts and results of
	320	expressions are also truncated.
	321
	322	Unlike L<integer>, this pragma creates integer constants that are only
	323	limited in their size by the available memory and CPU time.
	324
	325	=head2 use integer vs. use bigint
	326
	327	There is one small difference between C<use integer> and C<use bigint>: the
	328	former will not affect assignments to variables and the return value of
	329	some functions. C<bigint> truncates these results to integer too:
	330
	331	# perl -Minteger -wle 'print 3.2'
	332	3.2
	333	# perl -Minteger -wle 'print 3.2 + 0'
	334	3
	335	# perl -Mbigint -wle 'print 3.2'
	336	3
	337	# perl -Mbigint -wle 'print 3.2 + 0'
	338	3
	339
	340	# perl -Mbigint -wle 'print exp(1) + 0'
	341	2
	342	# perl -Mbigint -wle 'print exp(1)'
	343	2
d1a15766	344	# perl -Minteger -wle 'print exp(1)'
1ad2138d	345	2.71828182845905
d1a15766	346	# perl -Minteger -wle 'print exp(1) + 0'
1ad2138d	347	2
	348
	349	In practice this makes seldom a difference as B<parts and results> of
	350	expressions will be truncated anyway, but this can, for instance, affect the
	351	return value of subroutines:
	352
	353	sub three_integer { use integer; return 3.2; }
	354	sub three_bigint { use bigint; return 3.2; }
	355
	356	print three_integer(), " ", three_bigint(),"\n"; # prints "3.2 3"
126f3c5f	357
b68b7ab1	358	=head2 Options
126f3c5f	359
	360	bigint recognizes some options that can be passed while loading it via use.
	361	The options can (currently) be either a single letter form, or the long form.
	362	The following options exist:
	363
	364	=over 2
	365
	366	=item a or accuracy
	367
	368	This sets the accuracy for all math operations. The argument must be greater
	369	than or equal to zero. See Math::BigInt's bround() function for details.
	370
	371	perl -Mbigint=a,2 -le 'print 12345+1'
	372
95a2d02c	373	Note that setting precision and accurary at the same time is not possible.
95a2d02c	374
126f3c5f	375	=item p or precision
	376
	377	This sets the precision for all math operations. The argument can be any
	378	integer. Negative values mean a fixed number of digits after the dot, and
	379	are <B>ignored</B> since all operations happen in integer space.
	380	A positive value rounds to this digit left from the dot. 0 or 1 mean round to
	381	integer and are ignore like negative values.
	382
	383	See Math::BigInt's bfround() function for details.
	384
	385	perl -Mbignum=p,5 -le 'print 123456789+123'
	386
95a2d02c	387	Note that setting precision and accurary at the same time is not possible.
95a2d02c	388
126f3c5f	389	=item t or trace
	390
	391	This enables a trace mode and is primarily for debugging bigint or
	392	Math::BigInt.
	393
d1a15766	394	=item hex
	395
	396	Override the build-in hex() method with a version that can handle big
	397	integers. Note that under Perl v5.9.4 or ealier, this will be global
	398	and cannot be disabled with "no bigint;".
	399
	400	=item oct
	401
	402	Override the build-in oct() method with a version that can handle big
	403	integers. Note that under Perl v5.9.4 or ealier, this will be global
	404	and cannot be disabled with "no bigint;".
	405
bd49aa09	406	=item l, lib, try or only
126f3c5f	407
bd49aa09	408	Load a different math lib, see L<Math Library>.
126f3c5f	409
bd49aa09	410	perl -Mbigint=lib,GMP -e 'print 2 ** 512'
	411	perl -Mbigint=try,GMP -e 'print 2 ** 512'
	412	perl -Mbigint=only,GMP -e 'print 2 ** 512'
126f3c5f	413
126f3c5f	414	Currently there is no way to specify more than one library on the command
95a2d02c	415	line. This means the following does not work:
	416
	417	perl -Mbignum=l,GMP,Pari -e 'print 2 ** 512'
	418
	419	This will be hopefully fixed soon ;)
126f3c5f	420
	421	=item v or version
	422
	423	This prints out the name and version of all modules used and then exits.
	424
b68b7ab1	425	perl -Mbigint=v
126f3c5f	426
95a2d02c	427	=back
95a2d02c	428
b68b7ab1	429	=head2 Math Library
126f3c5f	430
	431	Math with the numbers is done (by default) by a module called
	432	Math::BigInt::Calc. This is equivalent to saying:
	433
	434	use bigint lib => 'Calc';
	435
	436	You can change this by using:
	437
bd49aa09	438	use bignum lib => 'GMP';
126f3c5f	439
	440	The following would first try to find Math::BigInt::Foo, then
	441	Math::BigInt::Bar, and when this also fails, revert to Math::BigInt::Calc:
	442
	443	use bigint lib => 'Foo,Math::BigInt::Bar';
	444
bd49aa09	445	Using C<lib> warns if none of the specified libraries can be found and
	446	L<Math::BigInt> did fall back to one of the default libraries.
	447	To supress this warning, use C<try> instead:
	448
	449	use bignum try => 'GMP';
	450
	451	If you want the code to die instead of falling back, use C<only> instead:
	452
	453	use bignum only => 'GMP';
	454
126f3c5f	455	Please see respective module documentation for further details.
126f3c5f	456
b68b7ab1	457	=head2 Internal Format
126f3c5f	458
	459	The numbers are stored as objects, and their internals might change at anytime,
	460	especially between math operations. The objects also might belong to different
	461	classes, like Math::BigInt, or Math::BigInt::Lite. Mixing them together, even
	462	with normal scalars is not extraordinary, but normal and expected.
	463
	464	You should not depend on the internal format, all accesses must go through
990fb837	465	accessor methods. E.g. looking at $x->{sign} is not a good idea since there
126f3c5f	466	is no guaranty that the object in question has such a hash key, nor is a hash
	467	underneath at all.
	468
b68b7ab1	469	=head2 Sign
126f3c5f	470
b68b7ab1	471	The sign is either '+', '-', 'NaN', '+inf' or '-inf'.
126f3c5f	472	You can access it with the sign() method.
	473
	474	A sign of 'NaN' is used to represent the result when input arguments are not
	475	numbers or as a result of 0/0. '+inf' and '-inf' represent plus respectively
	476	minus infinity. You will get '+inf' when dividing a positive number by 0, and
	477	'-inf' when dividing any negative number by 0.
	478
b68b7ab1	479	=head2 Methods
126f3c5f	480
	481	Since all numbers are now objects, you can use all functions that are part of
	482	the BigInt API. You can only use the bxxx() notation, and not the fxxx()
	483	notation, though.
	484
95a2d02c	485	=over 2
	486
	487	=item inf()
	488
	489	A shortcut to return Math::BigInt->binf(). Useful because Perl does not always
	490	handle bareword C<inf> properly.
	491
	492	=item NaN()
	493
	494	A shortcut to return Math::BigInt->bnan(). Useful because Perl does not always
	495	handle bareword C<NaN> properly.
	496
fade31f0	497	=item e()
	498
	499	Returns Euler's number C<e>, aka exp(1), to the given number of digits.
	500
	501	=item PI()
	502
	503	Returns PI to the given number of digits.
	504
95a2d02c	505	=item upgrade()
	506
	507	Return the class that numbers are upgraded to, is in fact returning
	508	C<$Math::BigInt::upgrade>.
	509
4440d13a	510	=item in_effect()
	511
	512	use bigint;
	513
	514	print "in effect\n" if bigint::in_effect; # true
	515	{
	516	no bigint;
	517	print "in effect\n" if bigint::in_effect; # false
	518	}
	519
	520	Returns true or false if C<bigint> is in effect in the current scope.
	521
	522	This method only works on Perl v5.9.4 or later.
	523
95a2d02c	524	=back
	525
	526	=head2 MATH LIBRARY
	527
	528	Math with the numbers is done (by default) by a module called
	529
b68b7ab1	530	=head2 Caveat
990fb837	531
	532	But a warning is in order. When using the following to make a copy of a number,
	533	only a shallow copy will be made.
	534
	535	$x = 9; $y = $x;
	536	$x = $y = 7;
	537
	538	Using the copy or the original with overloaded math is okay, e.g. the
	539	following work:
	540
	541	$x = 9; $y = $x;
	542	print $x + 1, " ", $y,"\n"; # prints 10 9
	543
	544	but calling any method that modifies the number directly will result in
3c4b39be	545	B<both> the original and the copy being destroyed:
990fb837	546
	547	$x = 9; $y = $x;
	548	print $x->badd(1), " ", $y,"\n"; # prints 10 10
	549
	550	$x = 9; $y = $x;
	551	print $x->binc(1), " ", $y,"\n"; # prints 10 10
	552
	553	$x = 9; $y = $x;
	554	print $x->bmul(2), " ", $y,"\n"; # prints 18 18
	555
	556	Using methods that do not modify, but testthe contents works:
	557
	558	$x = 9; $y = $x;
	559	$z = 9 if $x->is_zero(); # works fine
	560
	561	See the documentation about the copy constructor and C<=> in overload, as
	562	well as the documentation in BigInt for further details.
	563
d1a15766	564	=head1 CAVAETS
	565
	566	=over 2
	567
	568	=item in_effect()
	569
	570	This method only works on Perl v5.9.4 or later.
	571
	572	=item hex()/oct()
	573
	574	C<bigint> overrides these routines with versions that can also handle
	575	big integer values. Under Perl prior to version v5.9.4, however, this
	576	will not happen unless you specifically ask for it with the two
	577	import tags "hex" and "oct" - and then it will be global and cannot be
	578	disabled inside a scope with "no bigint":
	579
	580	use bigint qw/hex oct/;
	581
	582	print hex("0x1234567890123456");
	583	{
	584	no bigint;
	585	print hex("0x1234567890123456");
	586	}
	587
	588	The second call to hex() will warn about a non-portable constant.
	589
	590	Compare this to:
	591
	592	use bigint;
	593
	594	# will warn only under Perl older than v5.9.4
	595	print hex("0x1234567890123456");
	596
	597	=back
	598
126f3c5f	599	=head1 MODULES USED
	600
	601	C<bigint> is just a thin wrapper around various modules of the Math::BigInt
	602	family. Think of it as the head of the family, who runs the shop, and orders
	603	the others to do the work.
	604
	605	The following modules are currently used by bigint:
	606
	607	Math::BigInt::Lite (for speed, and only if it is loadable)
	608	Math::BigInt
	609
	610	=head1 EXAMPLES
	611
	612	Some cool command line examples to impress the Python crowd ;) You might want
	613	to compare them to the results under -Mbignum or -Mbigrat:
	614
	615	perl -Mbigint -le 'print sqrt(33)'
	616	perl -Mbigint -le 'print 2*255'
	617	perl -Mbigint -le 'print 4.5+2*255'
	618	perl -Mbigint -le 'print 3/7 + 5/7 + 8/3'
	619	perl -Mbigint -le 'print 123->is_odd()'
	620	perl -Mbigint -le 'print log(2)'
	621	perl -Mbigint -le 'print 2 ** 0.5'
	622	perl -Mbigint=a,65 -le 'print 2 ** 0.2'
95a2d02c	623	perl -Mbignum=a,65,l,GMP -le 'print 7 ** 7777'
126f3c5f	624
	625	=head1 LICENSE
	626
	627	This program is free software; you may redistribute it and/or modify it under
	628	the same terms as Perl itself.
	629
	630	=head1 SEE ALSO
	631
	632	Especially L<bigrat> as in C<perl -Mbigrat -le 'print 1/3+1/4'> and
	633	L<bignum> as in C<perl -Mbignum -le 'print sqrt(2)'>.
	634
	635	L<Math::BigInt>, L<Math::BigRat> and L<Math::Big> as well
	636	as L<Math::BigInt::BitVect>, L<Math::BigInt::Pari> and L<Math::BigInt::GMP>.
	637
	638	=head1 AUTHORS
	639
95a2d02c	640	(C) by Tels L<http://bloodgate.com/> in early 2002 - 2007.
126f3c5f	641
126f3c5f	642	=cut