doco on bitwise logicals

[Kevin Ryde <user42@zip.com.au>]

[-- Attachment #1: Type: text/plain, Size: 2336 bytes --]

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



[-- Attachment #2: scheme-data.texi.bitwise.diff --]
[-- Type: text/plain, Size: 3218 bytes --]

--- scheme-data.texi.~1.26.~	2003-05-04 08:43:27.000000000 +1000
+++ scheme-data.texi	2003-05-04 10:49:27.000000000 +1000
@@ -1055,7 +1055,13 @@
 @node Bitwise Operations
 @subsection Bitwise Operations
 
-@deffn {Scheme Procedure} logand n1 n2
+For the following bitwise functions, negative numbers are treated as
+infinite precision twos-complements.  For instance @math{-6} is bits
+@math{@dots{}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.
+
+@deffn {Scheme Procedure} logand n1 n2 @dots{}
 Return the bitwise @sc{and} of the integer arguments.
 
 @lisp
@@ -1065,7 +1071,7 @@
 @end lisp
 @end deffn
 
-@deffn {Scheme Procedure} logior n1 n2
+@deffn {Scheme Procedure} logior n1 n2 @dots{}
 Return the bitwise @sc{or} of the integer arguments.
 
 @lisp
@@ -1075,9 +1081,10 @@
 @end lisp
 @end deffn
 
-@deffn {Scheme Procedure} logxor n1 n2
+@deffn {Scheme Procedure} logxor n1 n2 @dots{}
 Return the bitwise @sc{xor} of the integer arguments.  A bit is
 set in the result if it is set in an odd number of arguments.
+
 @lisp
 (logxor) @result{} 0
 (logxor 7) @result{} 7
@@ -1088,8 +1095,8 @@
 
 @deffn {Scheme Procedure} lognot n
 @deffnx {C Function} scm_lognot (n)
-Return the integer which is the 2s-complement of the integer
-argument.
+Return the integer which is the ones-complement of the integer
+argument, ie.@: each 0 bit is changed to 1 and each 1 bit to 0.
 
 @lisp
 (number->string (lognot #b10000000) 2)
@@ -1124,16 +1131,19 @@
 
 @deffn {Scheme Procedure} ash n cnt
 @deffnx {C Function} scm_ash (n, cnt)
-The function @code{ash} performs an arithmetic shift left by @var{cnt}
-bits (or shift right, if @var{cnt} is negative).  `Arithmetic'
-means that the function does not guarantee to keep the bit
-structure of @var{n}, but rather guarantees that the result
-will always be rounded towards minus infinity.  Therefore, the
-results of @code{ash} and a corresponding bitwise shift will differ if
-@var{n} is negative.
+Return @var{n} shifted left by @var{cnt} bits, or shifted right if
+@var{cnt} is negative.  This is an ``arithmetic'' shift.
 
-Formally, the function returns an integer equivalent to
-@code{(inexact->exact (floor (* @var{n} (expt 2 @var{cnt}))))}.
+This corresponds to a multiplication by @math{2^@var{cnt}}.  When
+@var{cnt} is negative it's a division, and the rounding is towards
+negative infinity.  (Note that this is not the same rounding as
+@code{quotient} does.)
+
+With @var{n} viewed as an infinite precision twos complement,
+@code{ash} means a left shift introducing zero bits, or a right shift
+dropping bits.  For instance @math{-23} is @math{@dots{}11101001},
+which shifted by a @var{cnt} of @math{-2} drops two bits to give
+@math{@dots{}111010}, which is @math{-6}.
 
 @lisp
 (number->string (ash #b1 3) 2)     @result{} "1000"
@@ -1162,6 +1172,10 @@
 @deffnx {C Function} scm_integer_length (n)
 Return the number of bits necessary to represent @var{n}.
 
+For positive @var{n} this is how many bits to the highest one bit.
+For negative @var{n} it's how many bits to the highest zero bit in
+twos complement form.
+
 @lisp
 (integer-length #b10101010)
    @result{} 8

[-- Attachment #3: Type: text/plain, Size: 142 bytes --]

_______________________________________________
Guile-devel mailing list
Guile-devel@gnu.org
http://mail.gnu.org/mailman/listinfo/guile-devel