[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};
  }

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

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