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

package bigint;
use 5.006002;

$VERSION = '0.10';
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 $lib_kind = 'try';

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

  bigint->accuracy($a) if defined $a;
  bigint->precision($p) if defined $p;
  if ($ver)
    {
    print "bigint\t\t\t v$VERSION\n";
    print "Math::BigInt::Lite\t v$Math::BigInt::Lite::VERSION\n" if $_lite;
    print "Math::BigInt\t\t v$Math::BigInt::VERSION";
    my $config = Math::BigInt->config();
    print " lib => $config->{lib} v$config->{lib_version}\n";
    exit;
    }
  # we take care of floating point constants, since BigFloat isn't available
  # and BigInt doesn't like them:
  overload::constant float => sub { Math::BigInt->new( _float_constant(shift) ); };
  # Take care of octal/hexadecimal constants
  overload::constant binary => sub { _binary_constant(shift) };

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

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