doco on bitwise logicals

[Kevin Ryde]

I thought it might be nice to add some overall words about twos
complement negatives for the bitwise functions, and I think ash can be
clarified by talking about that.  Without wanting to be critical, I
don't think "not guarantee to keep the bit-structure of N" is as
enlightening as it could be.

        * scheme-data.texi (Bitwise Operations): Note negatives are treated as
        infinite precision twos complement.  Revise `ash' to emphasise this
        for right shifts of negatives.  Describe integer-length behaviour on
        negatives.  Add `...' to logand, logior, logxor since they take
        multiple parameters.

Assuming all this is meant to be documented features of course :-).

It occurs to me that integer-length is perhaps not ideal in returning
0 for an argument of -1.  But very likely it's too late to change
that.

New text for ease of contemplation:


For the following bitwise functions, negative numbers are treated as
infinite precision twos-complements.  For instance -6 is bits
...111010, with infinitely many ones on the left.  It can be seen that
adding 6 (binary 110) to such a bit pattern gives all zeros.


 - Scheme Procedure: ash n cnt
 - C Function: scm_ash (n, cnt)
     Return N shifted left by CNT bits, or shifted right if CNT is
     negative.  This is an "arithmetic" shift.

     This corresponds to a multiplication by 2^CNT.  When CNT is
     negative it's a division, and the rounding is towards negative
     infinity.  (Note that this is not the same rounding as `quotient'
     does.)

     With N viewed as an infinite precision twos complement, `ash'
     means a left shift introducing zero bits, or a right shift
     dropping bits.  For instance -23 is ...11101001, which shifted by
     a CNT of -2 drops two bits to give ...111010, which is -6.

          (number->string (ash #b1 3) 2)     => "1000"
          (number->string (ash #b1010 -1) 2) => "101"

 - Scheme Procedure: integer-length n
 - C Function: scm_integer_length (n)
     Return the number of bits necessary to represent N.

     For positive N this is how many bits to the highest one bit.  For
     negative N it's how many bits to the highest zero bit in twos
     complement form.

          (integer-length #b10101010)
             => 8
          (integer-length 0)
             => 0
          (integer-length #b1111)
             => 4

scheme-data.texi.bitwise.diff
Description: Text document