X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2Finteger.pm;h=caa1ea6951fa1426760ca8a36677e1d1f8852b70;hb=73e51c8a2e5bd997f8b13e4f86b01e266a2d73f5;hp=f720ce56d07eea1c3b93d55c4bf8b93acb445463;hpb=34bbe29d1876bdcabf8635bd358d9faecae0905e;p=p5sagit%2Fp5-mst-13.2.git

diff --git a/lib/integer.pm b/lib/integer.pm
index f720ce5..caa1ea6 100644
--- a/lib/integer.pm
+++ b/lib/integer.pm
@@ -19,25 +19,34 @@ of the enclosing BLOCK.  On many machines, this doesn't matter a great
 deal for most computations, but on those without floating point
 hardware, it can make a big difference in performance.
 
-Note that this only affects how certain operators handle their operands
-and results, and not all numbers everywhere.  Specifically, C<use
-integer;> has the effect that before computing the result of X + Y, X -
-Y, X / Y, X * Y, X % Y, or -X (unary minus), the operands X and Y have
-their fractional portions truncated, and the result will have its
-fractional portion truncated as well.  For example, this code
+Note that this only affects how most of the arithmetic and relational
+B<operators> handle their operands and results, and B<not> how all
+numbers everywhere are treated.  Specifically, C<use integer;> has the
+effect that before computing the results of the arithmetic operators
+(+, -, *, /, %, +=, -=, *=, /=, %=, and unary minus), the comparison
+operators (<, <=, >, >=, ==, !=, <=>), and the bitwise operators (|, &,
+^, <<, >>, |=, &=, ^=, <<=, >>=), the operands have their fractional
+portions truncated (or floored), and the result will have its
+fractional portion truncated as well.  In addition, the range of
+operands and results is restricted to that of familiar two's complement
+integers, i.e., -(2**31) .. (2**31-1) on 32-bit architectures, and
+-(2**63) .. (2**63-1) on 64-bit architectures.  For example, this code
 
     use integer;
     $x = 5.8;
     $y = 2.5;
+    $z = 2.7;
+    $a = 2**31 - 1;  # Largest positive integer on 32-bit machines
     $, = ", ";
-    print $x, -$x, $x + $y, $x - $y, $x / $y, $x * $y;
+    print $x, -$x, $x + $y, $x - $y, $x / $y, $x * $y, $y == $z, $a, $a + 1;
 
-will print:  5.8, -5, 7, 3, 2, 10
+will print:  5.8, -5, 7, 3, 2, 10, 1, 2147483647, -2147483648
 
 Note that $x is still printed as having its true non-integer value of
-5.8 since it wasn't operated on.  Also, arguments passed to functions
-and the values returned by them are not affected by C<use integer;>.
-E.g.,
+5.8 since it wasn't operated on.  And note too the wrap-around from the
+largest positive integer to the largest negative one.   Also, arguments
+passed to functions and the values returned by them are B<not> affected
+by C<use integer;>.  E.g.,
 
     srand(1.5);
     $, = ", ";
@@ -45,13 +54,16 @@ E.g.,
 
 will give the same result with or without C<use integer;>  The power
 operator C<**> is also not affected, so that 2 ** .5 is always the
-square root of 2.
+square root of 2.  Now, it so happens that the pre- and post- increment
+and decrement operators, ++ and --, are not affected by C<use integer;>
+either.  Some may rightly consider this to be a bug -- but at least it's
+a long-standing one.
 
-Finally, C<use integer;> also has an affect on the bitwise operators
-"&", "|", "^", "~", "<<", and ">>".  Normally, the operands and results
-are treated as unsigned integers, but with C<use integer;> the operands
-and results are signed.  This means, among other things, that ~0 is -1,
-and -2 & -5 is -6.
+Finally, C<use integer;> also has an additional affect on the bitwise
+operators.  Normally, the operands and results are treated as
+B<unsigned> integers, but with C<use integer;> the operands and results
+are B<signed>.  This means, among other things, that ~0 is -1, and -2 &
+-5 is -6.
 
 Internally, native integer arithmetic (as provided by your C compiler)
 is used.  This means that Perl's own semantics for arithmetic
@@ -64,7 +76,7 @@ may do another.
     % perl -Minteger -le 'print (4 % -3)'
     1
 
-See L<perlmod/Pragmatic Modules>.
+See L<perlmodlib/"Pragmatic Modules">, L<perlop/"Integer Arithmetic">
 
 =cut