[perl5.git] / lib / bigint.pm

package bigint;
require 5.005;

$VERSION = '0.03';
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])
          {
          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];
#    }
  return $Math::BigInt::upgrade;
  }

sub _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);
  return $sign.$$miv.$mfv; 			# 123.45e+1 => 1234
  }

sub import 
  {
  my $self = shift;

  # some defaults
  my $lib = 'Calc';

  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
    } 
  # Math::BigInt::Trace or plain Math::BigInt
  $class->import(@import, lib => $lib);

  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( _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 bignt;

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

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

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

=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 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 -e ''

=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 bright 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' and stored seperately.
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. 

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

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

=cut
Commit	Line	Data
126f3c5f JH	1	package bigint;
	2	require 5.005;
	3
b4bc5691	4	$VERSION = '0.03';
126f3c5f	5	use Exporter;
b4bc5691 T	6	@ISA = qw( Exporter );
	7	@EXPORT_OK = qw( );
	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	{
	36	Math::BigInt->$name($_[0]);
	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	# }
	57	return $Math::BigInt::upgrade;
	58	}
	59
	60	sub _constant
	61	{
	62	# this takes a floating point constant string and returns it truncated to
	63	# integer. For instance, '4.5' => '4', '1.234e2' => '123' etc
	64	my $float = shift;
	65
	66	# some simple cases first
	67	return $float if ($float =~ /^[+-]?[0-9]+$/); # '+123','-1','0' etc
	68	return $float
	69	if ($float =~ /^[+-]?[0-9]+\.?[eE]\+?[0-9]+$/); # 123e2, 123.e+2
	70	return '0' if ($float =~ /^[+-]?[0]*\.[0-9]+$/); # .2, 0.2, -.1
	71	if ($float =~ /^[+-]?[0-9]+\.[0-9]*$/) # 1., 1.23, -1.2 etc
	72	{
73	$float =~ s/\..*//;
74	return $float;
75	}
76	my ($mis,$miv,$mfv,$es,$ev) = Math::BigInt::_split(\$float);
77	return $float if !defined $mis; # doesn't look like a number to me
78	my $ec = int($$ev);
79	my $sign = $$mis; $sign = '' if $sign eq '+';
80	if ($$es eq '-')
81	{
82	# ignore fraction part entirely
83	if ($ec >= length($$miv)) # 123.23E-4
84	{
85	return '0';
86	}
87	return $sign . substr ($$miv,0,length($$miv)-$ec); # 1234.45E-2 = 12
88	}
89	# xE+y
90	if ($ec >= length($$mfv))
91	{
92	$ec -= length($$mfv);
93	return $sign.$$miv.$$mfv if $ec == 0; # 123.45E+2 => 12345
94	return $sign.$$miv.$$mfv.'E'.$ec; # 123.45e+3 => 12345e1
95	}
96	$mfv = substr($$mfv,0,$ec);
97	return $sign.$$miv.$mfv; # 123.45e+1 => 1234
98	}
99
100	sub import
101	{
102	my $self = shift;
103
104	# some defaults
105	my $lib = 'Calc';
106
107	my @import = ( ':constant' ); # drive it w/ constant
108	my @a = @_; my $l = scalar @_; my $j = 0;
109	my ($ver,$trace); # version? trace?
110	my ($a,$p); # accuracy, precision
111	for ( my $i = 0; $i < $l ; $i++,$j++ )
112	{
113	if ($_[$i] =~ /^(l\|lib)$/)
114	{
115	# this causes a different low lib to take care...
116	$lib = $_[$i+1] \|\| '';
117	my $s = 2; $s = 1 if @a-$j < 2; # avoid "can not modify non-existant..."
118	splice @a, $j, $s; $j -= $s; $i++;
119	}
120	elsif ($_[$i] =~ /^(a\|accuracy)$/)
121	{
122	$a = $_[$i+1];
123	my $s = 2; $s = 1 if @a-$j < 2; # avoid "can not modify non-existant..."
124	splice @a, $j, $s; $j -= $s; $i++;
125	}
126	elsif ($_[$i] =~ /^(p\|precision)$/)
127	{
128	$p = $_[$i+1];
129	my $s = 2; $s = 1 if @a-$j < 2; # avoid "can not modify non-existant..."
130	splice @a, $j, $s; $j -= $s; $i++;
131	}
132	elsif ($_[$i] =~ /^(v\|version)$/)
133	{
134	$ver = 1;
135	splice @a, $j, 1; $j --;
136	}
137	elsif ($_[$i] =~ /^(t\|trace)$/)
138	{
139	$trace = 1;
140	splice @a, $j, 1; $j --;
141	}
142	else { die "unknown option $_[$i]"; }
143	}
144	my $class;
145	$_lite = 0; # using M::BI::L ?
146	if ($trace)
147	{
148	require Math::BigInt::Trace; $class = 'Math::BigInt::Trace';
126f3c5f JH	149	}
	150	else
	151	{
	152	# see if we can find Math::BigInt::Lite
	153	if (!defined $a && !defined $p) # rounding won't work to well
	154	{
	155	eval 'require Math::BigInt::Lite;';
	156	if ($@ eq '')
	157	{
	158	@import = ( ); # :constant in Lite, not MBI
	159	Math::BigInt::Lite->import( ':constant' );
	160	$_lite= 1; # signal okay
	161	}
	162	}
	163	require Math::BigInt if $_lite == 0; # not already loaded?
	164	$class = 'Math::BigInt'; # regardless of MBIL or not
	165	}
	166	# Math::BigInt::Trace or plain Math::BigInt
	167	$class->import(@import, lib => $lib);
	168
	169	bigint->accuracy($a) if defined $a;
	170	bigint->precision($p) if defined $p;
	171	if ($ver)
	172	{
	173	print "bigint\t\t\t v$VERSION\n";
	174	print "Math::BigInt::Lite\t v$Math::BigInt::Lite::VERSION\n" if $_lite;
	175	print "Math::BigInt\t\t v$Math::BigInt::VERSION";
	176	my $config = Math::BigInt->config();
	177	print " lib => $config->{lib} v$config->{lib_version}\n";
	178	exit;
	179	}
	180	# we take care of floating point constants, since BigFloat isn't available
	181	# and BigInt doesn't like them:
	182	overload::constant float => sub { Math::BigInt->new( _constant(shift) ); };
b4bc5691 T	183
b4bc5691 T	184	$self->export_to_level(1,$self,@a); # export inf and NaN
126f3c5f JH	185	}
126f3c5f JH	186
b4bc5691 T	187	sub inf () { Math::BigInt->binf(); }
	188	sub NaN () { Math::BigInt->bnan(); }
	189
126f3c5f JH	190	1;
	191
	192	__END__
	193
	194	=head1 NAME
	195
b4bc5691	196	bigint - Transparent BigInteger support for Perl
126f3c5f JH	197
	198	=head1 SYNOPSIS
	199
	200	use bignt;
	201
	202	$x = 2 + 4.5,"\n"; # BigInt 6
b4bc5691 T	203	print 2 ** 512,"\n"; # really is what you think it is
	204	print inf + 42,"\n"; # inf
	205	print NaN * 7,"\n"; # NaN
126f3c5f JH	206
	207	=head1 DESCRIPTION
	208
	209	All operators (including basic math operations) are overloaded. Integer
	210	constants are created as proper BigInts.
	211
	212	Floating point constants are truncated to integer. All results are also
	213	trunctaed.
	214
	215	=head2 OPTIONS
	216
	217	bigint recognizes some options that can be passed while loading it via use.
	218	The options can (currently) be either a single letter form, or the long form.
	219	The following options exist:
	220
	221	=over 2
	222
	223	=item a or accuracy
	224
	225	This sets the accuracy for all math operations. The argument must be greater
	226	than or equal to zero. See Math::BigInt's bround() function for details.
	227
	228	perl -Mbigint=a,2 -le 'print 12345+1'
	229
	230	=item p or precision
	231
	232	This sets the precision for all math operations. The argument can be any
	233	integer. Negative values mean a fixed number of digits after the dot, and
	234	are <B>ignored</B> since all operations happen in integer space.
	235	A positive value rounds to this digit left from the dot. 0 or 1 mean round to
	236	integer and are ignore like negative values.
	237
	238	See Math::BigInt's bfround() function for details.
	239
	240	perl -Mbignum=p,5 -le 'print 123456789+123'
	241
	242	=item t or trace
	243
	244	This enables a trace mode and is primarily for debugging bigint or
	245	Math::BigInt.
	246
	247	=item l or lib
	248
	249	Load a different math lib, see L<MATH LIBRARY>.
	250
	251	perl -Mbigint=l,GMP -e 'print 2 ** 512'
	252
	253	Currently there is no way to specify more than one library on the command
	254	line. This will be hopefully fixed soon ;)
	255
	256	=item v or version
	257
	258	This prints out the name and version of all modules used and then exits.
	259
	260	perl -Mbigint=v -e ''
	261
	262	=head2 MATH LIBRARY
	263
	264	Math with the numbers is done (by default) by a module called
	265	Math::BigInt::Calc. This is equivalent to saying:
	266
	267	use bigint lib => 'Calc';
	268
	269	You can change this by using:
270
271	use bigint lib => 'BitVect';
272
273	The following would first try to find Math::BigInt::Foo, then
274	Math::BigInt::Bar, and when this also fails, revert to Math::BigInt::Calc:
275
276	use bigint lib => 'Foo,Math::BigInt::Bar';
277
278	Please see respective module documentation for further details.
279
280	=head2 INTERNAL FORMAT
281
282	The numbers are stored as objects, and their internals might change at anytime,
283	especially between math operations. The objects also might belong to different
284	classes, like Math::BigInt, or Math::BigInt::Lite. Mixing them together, even
285	with normal scalars is not extraordinary, but normal and expected.
286
287	You should not depend on the internal format, all accesses must go through
288	accessor methods. E.g. looking at $x->{sign} is not a bright idea since there
289	is no guaranty that the object in question has such a hash key, nor is a hash
290	underneath at all.
291
292	=head2 SIGN
293
294	The sign is either '+', '-', 'NaN', '+inf' or '-inf' and stored seperately.
295	You can access it with the sign() method.
296
297	A sign of 'NaN' is used to represent the result when input arguments are not
298	numbers or as a result of 0/0. '+inf' and '-inf' represent plus respectively
299	minus infinity. You will get '+inf' when dividing a positive number by 0, and
300	'-inf' when dividing any negative number by 0.
301
302	=head2 METHODS
303
304	Since all numbers are now objects, you can use all functions that are part of
305	the BigInt API. You can only use the bxxx() notation, and not the fxxx()
306	notation, though.
307
308	=head1 MODULES USED
309
310	C<bigint> is just a thin wrapper around various modules of the Math::BigInt
311	family. Think of it as the head of the family, who runs the shop, and orders
312	the others to do the work.
313
314	The following modules are currently used by bigint:
315
316	Math::BigInt::Lite (for speed, and only if it is loadable)
317	Math::BigInt
318
319	=head1 EXAMPLES
320
321	Some cool command line examples to impress the Python crowd ;) You might want
322	to compare them to the results under -Mbignum or -Mbigrat:
323
324	perl -Mbigint -le 'print sqrt(33)'
325	perl -Mbigint -le 'print 2*255'
326	perl -Mbigint -le 'print 4.5+2*255'
327	perl -Mbigint -le 'print 3/7 + 5/7 + 8/3'
328	perl -Mbigint -le 'print 123->is_odd()'
329	perl -Mbigint -le 'print log(2)'
330	perl -Mbigint -le 'print 2 ** 0.5'
331	perl -Mbigint=a,65 -le 'print 2 ** 0.2'
332
333	=head1 LICENSE
334
335	This program is free software; you may redistribute it and/or modify it under
336	the same terms as Perl itself.
337
338	=head1 SEE ALSO
339
340	Especially L<bigrat> as in C<perl -Mbigrat -le 'print 1/3+1/4'> and
341	L<bignum> as in C<perl -Mbignum -le 'print sqrt(2)'>.
342
343	L<Math::BigInt>, L<Math::BigRat> and L<Math::Big> as well
344	as L<Math::BigInt::BitVect>, L<Math::BigInt::Pari> and L<Math::BigInt::GMP>.
345
346	=head1 AUTHORS
347
348	(C) by Tels L<http://bloodgate.com/> in early 2002.
349
350	=cut