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

package bigint;
use 5.006002;

$VERSION = '0.09';
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
  {
  my $self = shift;
  no strict 'refs';
#  if (defined $_[0])
#    {
#    $Math::BigInt::upgrade = $_[0];
#    }
  $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 import 
  {
  my $self = shift;

  # some defaults
  my $lib = '';

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

  $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

=head1 DESCRIPTION

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

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

=head2 Options

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

=over 2

=item a or accuracy

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

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

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

=item p or precision

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

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

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

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

=item t or trace

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

=item l or lib

Load a different math lib, see L<MATH LIBRARY>.

	perl -Mbigint=l,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 bigint lib => 'BitVect';

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';

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

=back

=head2 MATH LIBRARY

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

=head2 Caveat

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

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

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

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

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

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

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

=head1 MODULES USED

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

The following modules are currently used by bigint:

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

=head1 EXAMPLES

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

=head1 LICENSE

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

=head1 SEE ALSO

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

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

=head1 AUTHORS

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

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