[PATCH 5.5.64] perlnumber.pod

--- ./pod/perlnumber.pod~	Sun Feb 27 16:10:24 2000
+++ ./pod/perlnumber.pod	Sun Feb 27 16:16:34 2000
@@ -0,0 +1,180 @@
+=head1 NAME
+
+perlnumber - numbers in Perl and numeric operations
+
+=head1 SYNOPSIS
+
+    $n = 1234;			# Decimal integer
+    $n = 0b1110011;		# Binary integer
+    $n = 01234;			# Octal integer
+    $n = 0x1234;		# Hexadecimal integer
+    $n = 12.34e-56;		# Exponential notation
+    $n = "1234";		# Number given as string
+    $n = "-12.34e56";		# Number given as string
+
+=head1 DESCRIPTION
+
+This document describes how Perl I<core> treats variables with numeric values.
+There are additional ramifications related to treatment of numbers I<outside>
+of Perl core.  Say, operator overloading allows operations over arbitrarily
+large integers, floating points numbers with arbitrary precision, as well
+as operations over "exotic" numbers, such as modular arithmetic or p-adic
+arithmetic.  We completely ignore a possibility of operator overloading
+in this document, see L<perlovl> for details.
+
+Additionally, sometimes Perl may be compiled with options which make
+some non-numeric operations more convenient, the price being that numeric
+operations do not behave in a sane way.  Say, this may happen if Perl
+is compiled with 64-bit integers and 64-bit floating-point arithmetic.
+The descriptions of this document are not applicable to such Perls.
+
+=head1 Storing numbers
+
+Perl core can store numbers in 3 different formats: as native integers,
+as native floating point numbers, and as decimal strings.  Decimal strings
+may have an exponential notation part, as in C<"12.34e-56">.  I<Native>
+means "a format supported by the C compiler which built perl".
+
+Today "native" means exclusively binary format.  This is not that important
+with native integers, since all it does is it says that the limits for the
+maximal and the minimal supported native integer are close to powers of 2.
+However, for native floats this is the most fundamental restriction: native
+floats may represent only those numbers which have a "short" representation
+when converted to binary fraction.  Say, 0.9 cannot be respresented by a
+native float, since the binary fraction for 0.9 is infinite:
+
+  binary0.1110011001100...
+
+with C<1100> repeating again and again.  Additionally, the exponent of the binary
+number is also restricted.  On a typical hardware, floating point values
+can store numbers with up to 53 binary digits, and with binary exponents
+between -1024 and 1024.  In decimal this is close to 16 decimal digits
+and decimal exponents in the range of -304..304.  Say, on such machines
+Perl cannot store 12345678901234567 as a floating point number.
+
+Similarly, decimal strings may represent only those numbers which have a
+finite decimal expansion.  Being strings, thus of arbitrary length, there is
+no limit for the exponent or number of decimal digits for these numbers.
+(But keep in mind that what we discuss here is the rules for the I<storage>.
+The fact that you can store these numbers does not mean that that the
+I<operations> over these numbers will use all of the significant digits,
+see L<"Numeric operations and numeric conversions"> for details.)
+
+In fact numbers stored in the native integer format may be stored either
+in the signed native form, or in the unsigned native form.  Thus the limits
+for Perl numbers stored as native integers would typically be -2**31..2**32-1,
+with appropriate modifications in the case of 64-bit integers.  Again, this
+does not mean that Perl can do operations only over integers in this range:
+many more integers can be stored in a floating point format.
+
+Summing up, Perl numeric values can store only those numbers which have
+a finite decimal expansion or a "short" binary expansion.
+
+=head1 Numeric operators and numeric conversions
+
+Perl can store a number in any one of three formats, but most of Perl
+operators understand only one format.  When a numeric value is an argument
+of such an operator, it will be converted to the format understood to such
+an operator.
+
+There are 6 cases of such conversion: 
+
+  native_integer        --> native_floating_point	(*)
+  native_integer        --> decimal_string
+  native_floating_point --> native_integer		(*)
+  native_floating_point --> decimal_string		(*)
+  decimal_string        --> native_integer
+  decimal_string        --> native_floating_point	(*)
+
+These conversions are governed by the following general rules:
+
+=over
+
+=item *
+
+If the source number is representable in the target form, such a
+representation is used.
+
+=item *
+
+If the source number is outside of the limits representable in the target form,
+a representation of the closest limit is used.  (I<Loss of information>)
+
+=item *
+
+If the source number is between two numbers representable in the target form,
+a representation of one of these numbers is used.  (I<Loss of information>)
+
+=item *
+
+In C<native_floating_point --> native_integer> conversion the magnitude of the
+result is not larger than the magnitude of the source.  (I<"Rounding
+to zero".>)
+
+=item *
+
+If the C<decimal_string --> native_integer> conversion cannot be
+done without loss of information, is compatible with
+the chain C<decimal_string --> native_floating_point --> native_integer>.
+In particular, rounding is strongly biased to 0, though a number like
+C<"0.99999999999999999999"> has a chance to be rounded to 1.
+
+=back
+
+B<RESTRICTION>: The conversions marked with C<(*)> have components performed
+by the C compiler.  In particular, bugs/features of C compilers may lead to
+a breakage of some of the above rules.
+
+=head1 Flavors of Perl numeric operations
+
+Perl operations which take a numeric argument treat this argument in one
+of 4 different way: they may force it to the integer/floating/string format,
+or they may behave differently basing on the format of the operand.  Forcing
+a numeric value to a particular format does not change the number stored
+in the value.
+
+All the operators which need an argument in the integer format treat the
+argument as in modular arithmetic, say, C<mod 2**32> on 32-bit architecture.
+Say, C<sprintf "%u", -1> gives the same result as C<sprintf "%u", ~0>.
+
+=over
+
+=item Arithmetic operators except, C<no integer>
+
+force the argument to the floating point format.
+
+=item Arithmetic operators except, C<use integer>
+
+=item Bitwise operators, C<no integer>
+
+force the argument to the integer format if it is not a string.
+
+=item Bitwise operators, C<use integer>
+
+force the argument to the integer format (if it is not a string?),
+then do something?
+
+=item Operators which expect an integer
+
+force the argument to the integer format.  Say, this is applicable
+to the third and fourth arguments of C<sysread>.
+
+=item Operators which expect a string
+
+force the argument to the string format.  Say, this is applicable
+to C<printf "%s", $value>.
+
+=back
+
+Though forcing an argument to a particular form does not change the
+stored number, perl remembers the result of the conversion.  In particular,
+though a first forcing/conversion may be time-consuming, the repeated
+operations will not need to recalculate the conversion.
+
+=head1 AUTHOR
+
+Ilya Zakharevich C<ilya@math.ohio-state.edu>
+
+=head1 SEE ALSO
+
+See L<perlovl> for overloading of operators.
--- ./MANIFEST~	Wed Feb  2 04:54:34 2000
+++ ./MANIFEST	Sun Feb 27 16:11:46 2000
@@ -1086,6 +1086,7 @@ pod/perllol.pod		How to use lists of lis
 pod/perlmod.pod		Module mechanism info
 pod/perlmodinstall.pod	Installing CPAN Modules
 pod/perlmodlib.pod	Module policy info
+pod/perlnumber.pod	Numbers and numeric operations
 pod/perlobj.pod		Object info
 pod/perlop.pod		Operator info
 pod/perlopentut.pod	open() tutorial

• [PATCH 5.5.64] perlnumber.pod by Ilya Zakharevich