This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
perlfunc: Add caveat about string eval containing NV scalar
[perl5.git] / pod / perlnumber.pod
index c05b066..ffe3ed5 100644 (file)
@@ -4,15 +4,13 @@ perlnumber - semantics of numbers and numeric operations in Perl
 
 =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 = "-12.34e56";          # number specified as a string
-    $n = "1234";               # number specified as a string
-    $n = v49.50.51.52;         # number specified as a string, which in
-                               # turn is specified in terms of numbers :-)
+    $n = 1234;             # decimal integer
+    $n = 0b1110011;        # binary integer
+    $n = 01234;                    # octal integer
+    $n = 0x1234;           # hexadecimal integer
+    $n = 12.34e-56;        # exponential notation
+    $n = "-12.34e56";      # number specified as a string
+    $n = "1234";           # number specified as a string
 
 =head1 DESCRIPTION
 
@@ -22,11 +20,11 @@ Perl's operator overloading facility is completely ignored here.  Operator
 overloading allows user-defined behaviors for numbers, such as operations
 over arbitrarily large integers, floating points numbers with arbitrary
 precision, operations over "exotic" numbers such as modular arithmetic or
-p-adic arithmetic, and so on.  See L<perlovl> for details.
+p-adic arithmetic, and so on.  See L<overload> for details.
 
 =head1 Storing numbers
 
-Perl can internally represents numbers in 3 different ways: as native
+Perl can internally represent numbers in 3 different ways: 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> here means "a format supported by the C compiler which was used
@@ -36,10 +34,10 @@ The term "native" does not mean quite as much when we talk about native
 integers, as it does when native floating point numbers are involved.
 The only implication of the term "native" on integers is that the limits for
 the maximal and the minimal supported true integral quantities are close to
-powers of 2.  However, for "native" floats have a most fundamental
+powers of 2.  However, "native" floats have a most fundamental
 restriction: they may represent only those numbers which have a relatively
 "short" representation when converted to a binary fraction.  For example,
-0.9 cannot be respresented by a native float, since the binary fraction
+0.9 cannot be represented by a native float, since the binary fraction
 for 0.9 is infinite:
 
   binary0.1110011001100...
@@ -54,14 +52,14 @@ The upshot of all this is that Perl cannot store a number like
 12345678901234567 as a floating point number on such architectures without
 loss of information.
 
-Similarly, decimal strings may represent only those numbers which have a
+Similarly, decimal strings can represent only those numbers which have a
 finite decimal expansion.  Being strings, and thus of arbitrary length, there
 is no practical limit for the exponent or number of decimal digits for these
 numbers.  (But realize that what we are discussing the rules for just the
 I<storage> of these numbers.  The fact that you can store such "large" numbers
-does not mean that that the I<operations> over these numbers will use all
+does not mean that the I<operations> over these numbers will use all
 of the significant digits.
-See L<"Numeric operations and numeric conversions"> for details.)
+See L<"Numeric operators 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
@@ -91,7 +89,7 @@ Six such conversions are possible:
 
 These conversions are governed by the following general rules:
 
-=over
+=over 4
 
 =item *
 
@@ -141,21 +139,45 @@ argument as in modular arithmetic, e.g., C<mod 2**32> on a 32-bit
 architecture.  C<sprintf "%u", -1> therefore provides the same result as
 C<sprintf "%u", ~0>.
 
-=over
+=over 4
 
-=item Arithmetic operators except, C<no integer>
+=item Arithmetic operators
 
-force the argument into the floating point format.
+The binary operators C<+> C<-> C<*> C</> C<%> C<==> C<!=> C<E<gt>> C<E<lt>>
+C<E<gt>=> C<E<lt>=> and the unary operators C<-> C<abs> and C<--> will
+attempt to convert arguments to integers.  If both conversions are possible
+without loss of precision, and the operation can be performed without
+loss of precision then the integer result is used.  Otherwise arguments are
+converted to floating point format and the floating point result is used.
+The caching of conversions (as described above) means that the integer
+conversion does not throw away fractional parts on floating point numbers.
 
-=item Arithmetic operators except, C<use integer>
+=item ++
 
-=item Bitwise operators, C<no integer>
+C<++> behaves as the other operators above, except that if it is a string
+matching the format C</^[a-zA-Z]*[0-9]*\z/> the string increment described
+in L<perlop> is used.
 
-force the argument into the integer format if it is not a string.
+=item Arithmetic operators during C<use integer>
 
-=item Bitwise operators, C<use integer>
+In scopes where C<use integer;> is in force, nearly all the operators listed
+above will force their argument(s) into integer format, and return an integer
+result.  The exceptions, C<abs>, C<++> and C<-->, do not change their
+behavior with C<use integer;>
 
-force the argument into the integer format
+=item Other mathematical operators
+
+Operators such as C<**>, C<sin> and C<exp> force arguments to floating point
+format.
+
+=item Bitwise operators
+
+Arguments are forced into the integer format if not strings.
+
+=item Bitwise operators during C<use integer>
+
+forces arguments to integer format. Also shift operations internally use
+signed integers rather than the default unsigned.
 
 =item Operators which expect an integer
 
@@ -180,6 +202,8 @@ Ilya Zakharevich C<ilya@math.ohio-state.edu>
 
 Editorial adjustments by Gurusamy Sarathy <gsar@ActiveState.com>
 
+Updates for 5.8.0 by Nicholas Clark <nick@ccl4.org>
+
 =head1 SEE ALSO
 
-L<perlovl>
+L<overload>, L<perlop>