From mboxrd@z Thu Jan 1 00:00:00 1970 Path: main.gmane.org!not-for-mail From: Kevin Ryde Newsgroups: gmane.lisp.guile.devel Subject: doco on bitwise logicals Date: Sun, 04 May 2003 10:56:44 +1000 Sender: guile-devel-bounces+guile-devel=m.gmane.org@gnu.org Message-ID: <87vfwrjzqr.fsf@zip.com.au> NNTP-Posting-Host: main.gmane.org Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" X-Trace: main.gmane.org 1052009794 19680 80.91.224.249 (4 May 2003 00:56:34 GMT) X-Complaints-To: usenet@main.gmane.org NNTP-Posting-Date: Sun, 4 May 2003 00:56:34 +0000 (UTC) Original-X-From: guile-devel-bounces+guile-devel=m.gmane.org@gnu.org Sun May 04 02:56:31 2003 Return-path: Original-Received: from monty-python.gnu.org ([199.232.76.173]) by main.gmane.org with esmtp (Exim 3.35 #1 (Debian)) id 19C7nr-000577-00 for ; Sun, 04 May 2003 02:56:31 +0200 Original-Received: from localhost ([127.0.0.1] helo=monty-python.gnu.org) by monty-python.gnu.org with esmtp (Exim 4.10.13) id 19C7p2-00034S-01 for guile-devel@m.gmane.org; Sat, 03 May 2003 20:57:44 -0400 Original-Received: from list by monty-python.gnu.org with tmda-scanned (Exim 4.10.13) id 19C7oT-0002Ru-00 for guile-devel@gnu.org; Sat, 03 May 2003 20:57:09 -0400 Original-Received: from mail by monty-python.gnu.org with spam-scanned (Exim 4.10.13) id 19C7oL-0001wX-00 for guile-devel@gnu.org; Sat, 03 May 2003 20:57:07 -0400 Original-Received: from snoopy.pacific.net.au ([61.8.0.36]) by monty-python.gnu.org with esmtp (Exim 4.10.13) id 19C7oI-0001g2-00 for guile-devel@gnu.org; Sat, 03 May 2003 20:56:58 -0400 Original-Received: from sunny.pacific.net.au (sunny.pacific.net.au [203.2.228.40]) h440uts7007444 for ; Sun, 4 May 2003 10:56:55 +1000 Original-Received: from wisma.pacific.net.au (wisma.pacific.net.au [210.23.129.72]) by sunny.pacific.net.au with ESMTP id h440utQg009802 for ; Sun, 4 May 2003 10:56:55 +1000 (EST) Original-Received: from localhost (ppp30.dyn228.pacific.net.au [203.143.228.30]) by wisma.pacific.net.au (8.12.9/8.12.9) with ESMTP id h440urYZ004916 for ; Sun, 4 May 2003 10:56:53 +1000 (EST) Original-Received: from gg by localhost with local (Exim 3.35 #1 (Debian)) id 19C7o5-00049v-00; Sun, 04 May 2003 10:56:45 +1000 Original-To: guile-devel@gnu.org User-Agent: Gnus/5.090019 (Oort Gnus v0.19) Emacs/21.2 (gnu/linux) X-BeenThere: guile-devel@gnu.org X-Mailman-Version: 2.1b5 Precedence: list List-Id: Developers list for Guile, the GNU extensibility library List-Help: List-Post: List-Subscribe: , List-Archive: List-Unsubscribe: , Errors-To: guile-devel-bounces+guile-devel=m.gmane.org@gnu.org Xref: main.gmane.org gmane.lisp.guile.devel:2261 X-Report-Spam: http://spam.gmane.org/gmane.lisp.guile.devel:2261 --=-=-= 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 --=-=-= Content-Disposition: attachment; filename=scheme-data.texi.bitwise.diff --- 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 --=-=-= Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit _______________________________________________ Guile-devel mailing list Guile-devel@gnu.org http://mail.gnu.org/mailman/listinfo/guile-devel --=-=-=--