From a63df12168b2bac0d4c71725e75b9df53a595e21 Mon Sep 17 00:00:00 2001
From: Jarkko Hietaniemi
Date: Sun, 28 Jun 2015 08:47:25 0400
Subject: [PATCH] Document the new shift behaviors.

pod/perlop.pod  33 ++++++++++++++++++++++
1 file changed, 22 insertions(+), 11 deletions()
diff git a/pod/perlop.pod b/pod/perlop.pod
index 631b391..bed0695 100644
 a/pod/perlop.pod
+++ b/pod/perlop.pod
@@ 376,17 +376,28 @@ Binary C<<< ">>" >>> returns the value of its left argument shifted right by
the number of bits specified by the right argument. Arguments should
be integers. (See also L.)
Note that both C<<< << >>> and C<<< >> >>> in Perl are implemented directly using
C<<< << >>> and C<<< >> >>> in C. If S> (see L) is
in force then signed C integers are used, else unsigned C integers are
used, even for negative shiftees. Either way, the implementation isn't going to generate results
larger than the size of the integer type Perl was built with (32 bits
or 64 bits).

The result of overflowing the range of the integers is undefined
because it is undefined also in C. In other words, using 32bit
integers, S>> is undefined. Shifting by a negative number
of bits is also undefined.
+If S> (see L) is in force then
+signed C integers are used (I), otherwise unsigned C
+integers are used (I), even for negative shiftees.
+In arithmetic right shift the sign bit is replicated on the left,
+in logical shift zero bits come in from the left.
+
+Either way, the implementation isn't going to generate results larger
+than the size of the integer type Perl was built with (32 bits or 64 bits).
+
+Shifting by negative number of bits means the reverse shift: left
+shift becomes right shift, right shift becomes left shift. This is
+unlike in C, where negative shift is undefined.
+
+Shifting by more bits than the size of the integers means most of the
+time zero (all bits fall off), except that under S>
+right overshifting a negative shiftee results in 1. This is unlike
+in C, where shifting by too many bits is undefined. A common C
+behavior is "shift by modulo wordbits", so that for example
+
+ 1 >> 64 == 1 >> (64 % 64) == 1 >> 0 == 1 # Common C behavior.
+
+but that is completely accidental.
If you get tired of being subject to your platform's native integers,
the S> pragma neatly sidesteps the issue altogether:

1.8.3.1