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

package bignum;
require 5.005;

$VERSION = '0.12';
use Exporter;
@EXPORT_OK 	= qw( ); 
@EXPORT 	= qw( inf NaN ); 
@ISA 		= qw( Exporter );

use strict;

############################################################################## 

# 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)
      {
      *{"bignum::$name"} = sub 
        {
        my $self = shift;
        no strict 'refs';
        if (defined $_[0])
          {
          Math::BigInt->$name($_[0]);
          Math::BigFloat->$name($_[0]);
          }
        return Math::BigInt->$name();
        };
      return &$name;
      }
    }
 
  # delayed load of Carp and avoid recursion
  require Carp;
  Carp::croak ("Can't call bignum\-\>$name, not a valid method");
  }

sub upgrade
  {
  my $self = shift;
  no strict 'refs';
#  if (defined $_[0])
#    {
#    $Math::BigInt::upgrade = $_[0];
#    $Math::BigFloat::upgrade = $_[0];
#    }
  return $Math::BigInt::upgrade;
  }

sub import 
  {
  my $self = shift;

  # some defaults
  my $lib = 'Calc';
  my $upgrade = 'Math::BigFloat';
  my $downgrade = 'Math::BigInt';

  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] eq 'upgrade')
      {
      # this causes upgrading
      $upgrade = $_[$i+1];		# or undef to disable
      my $s = 2; $s = 1 if @a-$j < 2;	# avoid "can not modify non-existant..."
      splice @a, $j, $s; $j -= $s; $i++;
      }
    elsif ($_[$i] eq 'downgrade')
      {
      # this causes downgrading
      $downgrade = $_[$i+1];		# or undef to disable
      my $s = 2; $s = 1 if @a-$j < 2;	# avoid "can not modify non-existant..."
      splice @a, $j, $s; $j -= $s; $i++;
      }
    elsif ($_[$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';
    $upgrade = 'Math::BigFloat::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, upgrade => $upgrade, lib => $lib);

  if ($trace)
    {
    require Math::BigFloat::Trace; $class = 'Math::BigFloat::Trace';
    $downgrade = 'Math::BigInt::Trace';	
    }
  else
    {
    require Math::BigFloat; $class = 'Math::BigFloat';
    }
  $class->import(':constant','downgrade',$downgrade);

  bignum->accuracy($a) if defined $a;
  bignum->precision($p) if defined $p;
  if ($ver)
    {
    print "bignum\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";
    print "Math::BigFloat\t\t v$Math::BigFloat::VERSION\n";
    exit;
    }
  $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

bignum - Transparent BigNumber support for Perl

=head1 SYNOPSIS

  use bignum;

  $x = 2 + 4.5,"\n";			# BigFloat 6.5
  print 2 ** 512 * 0.1,"\n";		# really is what you think it is
  print inf * inf,"\n";			# prints inf
  print NaN * 3,"\n";			# prints NaN

=head1 DESCRIPTION

All operators (including basic math operations) are overloaded. Integer and
floating-point constants are created as proper BigInts or BigFloats,
respectively.

=head2 OPTIONS

bignum 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 -Mbignum=a,50 -le 'print sqrt(20)'

=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, while
a positive value rounds to this digit left from the dot. 0 or 1 mean round to
integer. See Math::BigInt's bfround() function for details.

	perl -Mbignum=p,-50 -le 'print sqrt(20)'

=item t or trace

This enables a trace mode and is primarily for debugging bignum or
Math::BigInt/Math::BigFloat.

=item l or lib

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

	perl -Mbignum=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 -Mbignum=v -e ''

=head2 METHODS

Beside import() and AUTOLOAD() there are only a few other methods.

=over 2

=item inf()

A shortcut to return Math::BigInt->binf(). Usefull because Perl does not always
handle bareword C<inf> properly.

=item NaN()

A shortcut to return Math::BigInt->bnan(). Usefull 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
Math::BigInt::Calc. This is equivalent to saying:

	use bignum lib => 'Calc';

You can change this by using:

	use bignum 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 bignum 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::BigFLoat. 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 hashkey, 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 or BigFloat API. It is wise to use only the bxxx() notation, and not
the fxxx() notation, though. This makes it possible that the underlying object
might morph into a different class than BigFloat.

=head1 MODULES USED

C<bignum> 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 bignum:

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

=head1 EXAMPLES

Some cool command line examples to impress the Python crowd ;)
 
	perl -Mbignum -le 'print sqrt(33)'
	perl -Mbignum -le 'print 2*255'
	perl -Mbignum -le 'print 4.5+2*255'
	perl -Mbignum -le 'print 3/7 + 5/7 + 8/3'
	perl -Mbignum -le 'print 123->is_odd()'
	perl -Mbignum -le 'print log(2)'
	perl -Mbignum -le 'print 2 ** 0.5'
	perl -Mbignum=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'>.

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