[perl5.git] / lib / bigint.pm

package bigint;
use 5.006;

$VERSION = '0.23';
use Exporter;
@ISA		= qw( Exporter );
@EXPORT_OK	= qw( PI e bpi bexp );
@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|bpi|bexp)\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); }
sub bpi ($) { Math::BigInt->new(3); }
sub bexp ($$) { my $x = Math::BigInt->new($_[0]); $x->bexp($_[1]); }

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

	# perl -Mbigint=e -wle 'print e'

Returns Euler's number C<e>, aka exp(1). Note that under bigint, this is
truncated to an integer, and hence simple '2'.

=item PI

	# perl -Mbigint=PI -wle 'print PI'

Returns PI. Note that under bigint, this is truncated to an integer, and hence
simple '3'.

=item bexp()

	bexp($power,$accuracy);

Returns Euler's number C<e> raised to the appropriate power, to
the wanted accuracy.

Note that under bigint, the result is truncated to an integer.

Example:

	# perl -Mbigint=bexp -wle 'print bexp(1,80)'

=item bpi()

	bpi($accuracy);

Returns PI to the wanted accuracy. Note that under bigint, this is truncated
to an integer, and hence simple '3'.

Example:

	# perl -Mbigint=bpi -wle 'print bpi(80)'

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