mailto:srfi-60@srfi.schemers.org.
See instructions
here to subscribe to the list. You can access previous messages via the
archive of the mailing list.
The discussions of the withdrawn SRFI-33: "Integer Bitwise-operation Library" seemed to founder on consistency of procedure names and arity; and on perceived competition with the boolean arrays of SRFI-47.
I have implemented both logical number operations and boolean arrays; and have not been conflicted as to their application. I used boolean arrays to construct very fast indexes for database tables having millions of records. To avoid running out of RAM, creation of megabit arrays should be explicit; so the boolean array procedures put their results into a passed array. In contrast, these procedures are purely functional.
The reference implementation is written using only Scheme integer operations. Thus the only exposure of the underlying representation is the ranges of fixnums.
The complement describes the representation of negative integers. With one's-complement fixnums, the range of integers is -(2n) to 2n, and there are two possible representations of 0. With two's-complement fixnums, the range of integers is -(2n+1) to 2n.
Since we treat integers as having two's-complement negations, the two's-complement of an integer is simply its negation. The one's-complement of an integer is computed by lognot:
(define (lognot n) (- -1 n))
In the Bitwise Operations, rather than striving for orthogonal completeness, I have concentrated on a nearly minimal set of bitwise logical functions sufficient to support the uses listed above.
Although any two of logior, logxor, and logand (in combination with lognot) are sufficient to generate all the two-input logic functions, having these three means that any nontrivial two-input logical function can be synthesized using just one of these two-input primaries with zero or one calls to lognot.
bitwise-if is what SRFI-33 calls bitwise-merge.
The SRFI-33 aliases: bitwise-ior, bitwise-xor, bitwise-and, bitwise-not, bitwise-merge, any-bits-set?, and bit-count are also provided.
log2-binary-factors (alias first-set-bit) is a useful function which is simple but non-obvious:
(define (log2-binary-factors n) (+ -1 (integer-length (logand n (- n)))))
I have changed to copy-bit-field argument order to be consistent with the other Field of Bits procedures: the start and end index arguments are last. This makes them analogous to the argument order to substring and SRFI-47 arrays, which took their cue from substring.
These start and end index arguments are not compatible with SRFI-33's size and position arguments (occurring first) in its bit-field procedures. Both define copy-bit-field; the arguments and purposes being incompatible.
A procedure in slib/logical.scm, logical:rotate, rotated a given number of low-order bits by a given number of bits. This function was quite servicable, but I could not name it adequately. I have replaced it with rotate-bit-field with the addition of a start argument. This new function rotates a given field (from positions start to end) within an integer; leaving the rest unchanged.
Another problematic name was logical:ones, which generated an integer with the least significant k bits set. Calls to bit-field could have replaced its uses . But the definition was so short that I just replaced its uses with:
(lognot (ash -1 k))
The bit-reverse procedure was then the only one which took a width argument. So I replaced it with reverse-bit-field.
The Lamination and Gray-code functions were moved to slib/phil-spc.scm
Example:
(number->string (logand #b1100 #b1010) 2)
=> "1000"
Example:
(number->string (logior #b1100 #b1010) 2)
=> "1110"
Example:
(number->string (logxor #b1100 #b1010) 2)
=> "110"
Example:
(number->string (lognot #b10000000) 2)
=> "-10000001"
(number->string (lognot #b0) 2)
=> "-1"
(logtest j k) == (not (zero? (logand j k))) (logtest #b0100 #b1011) => #f (logtest #b0100 #b0111) => #t
Example:
(logcount #b10101010)
=> 4
(logcount 0)
=> 0
(logcount -2)
=> 1
Example:
(integer-length #b10101010)
=> 8
(integer-length 0)
=> 0
(integer-length #b1111)
=> 4
(require 'printf)
(do ((idx 0 (+ 1 idx)))
((> idx 16))
(printf "%s(%3d) ==> %-5d %s(%2d) ==> %-5d\n"
'log2-binary-factors
(- idx) (log2-binary-factors (- idx))
'log2-binary-factors
idx (log2-binary-factors idx)))
-|
log2-binary-factors( 0) ==> -1 log2-binary-factors( 0) ==> -1
log2-binary-factors( -1) ==> 0 log2-binary-factors( 1) ==> 0
log2-binary-factors( -2) ==> 1 log2-binary-factors( 2) ==> 1
log2-binary-factors( -3) ==> 0 log2-binary-factors( 3) ==> 0
log2-binary-factors( -4) ==> 2 log2-binary-factors( 4) ==> 2
log2-binary-factors( -5) ==> 0 log2-binary-factors( 5) ==> 0
log2-binary-factors( -6) ==> 1 log2-binary-factors( 6) ==> 1
log2-binary-factors( -7) ==> 0 log2-binary-factors( 7) ==> 0
log2-binary-factors( -8) ==> 3 log2-binary-factors( 8) ==> 3
log2-binary-factors( -9) ==> 0 log2-binary-factors( 9) ==> 0
log2-binary-factors(-10) ==> 1 log2-binary-factors(10) ==> 1
log2-binary-factors(-11) ==> 0 log2-binary-factors(11) ==> 0
log2-binary-factors(-12) ==> 2 log2-binary-factors(12) ==> 2
log2-binary-factors(-13) ==> 0 log2-binary-factors(13) ==> 0
log2-binary-factors(-14) ==> 1 log2-binary-factors(14) ==> 1
log2-binary-factors(-15) ==> 0 log2-binary-factors(15) ==> 0
log2-binary-factors(-16) ==> 4 log2-binary-factors(16) ==> 4
(logbit? index n) == (logtest (expt 2 index) n) (logbit? 0 #b1101) => #t (logbit? 1 #b1101) => #f (logbit? 2 #b1101) => #t (logbit? 3 #b1101) => #t (logbit? 4 #b1101) => #f
#t and 0 if bit is #f.
Example:
(number->string (copy-bit 0 0 #t) 2) => "1" (number->string (copy-bit 2 0 #t) 2) => "100" (number->string (copy-bit 2 #b1111 #f) 2) => "1011"
Example:
(number->string (bit-field #b1101101010 0 4) 2)
=> "1010"
(number->string (bit-field #b1101101010 4 9) 2)
=> "10110"
Example:
(number->string (copy-bit-field #b1101101010 0 0 4) 2)
=> "1101100000"
(number->string (copy-bit-field #b1101101010 -1 0 4) 2)
=> "1101101111"
(number->string (copy-bit-field #b110100100010000 -1 5 9) 2)
=> "110100111110000"
(inexact->exact (floor (* n (expt 2 count)))).
Example:
(number->string (ash #b1 3) 2)
=> "1000"
(number->string (ash #b1010 -1) 2)
=> "101"
Example:
(number->string (rotate-bit-field #b0100 3 0 4) 2)
=> "10"
(number->string (rotate-bit-field #b0100 -1 0 4) 2)
=> "10"
(number->string (rotate-bit-field #b110100100010000 -1 5 9) 2)
=> "110100010010000"
(number->string (rotate-bit-field #b110100100010000 1 5 9) 2)
=> "110100000110000"
(number->string (reverse-bit-field #xa7 0 8) 16)
=> "e5"
integer->list returns a list of len booleans corresponding
to each bit of the given integer. #t is coded for each 1; #f for 0.
The len argument defaults to (integer-length k).
list->integer returns an integer formed from the booleans in the
list list, which must be a list of booleans. A 1 bit is coded for
each #t; a 0 bit for #f.
integer->list and list->integer are inverses so far as
equal? is concerned.
;;;; "logical.scm", bit access and operations for integers for Scheme
;;; Copyright (C) 1991, 1993, 2001, 2003, 2005 Aubrey Jaffer
;
;Permission to copy this software, to modify it, to redistribute it,
;to distribute modified versions, and to use it for any purpose is
;granted, subject to the following restrictions and understandings.
;
;1. Any copy made of this software must include this copyright notice
;in full.
;
;2. I have made no warranty or representation that the operation of
;this software will be error-free, and I am under no obligation to
;provide any services, by way of maintenance, update, or otherwise.
;
;3. In conjunction with products arising from the use of this
;material, there shall be no use of my name in any advertising,
;promotional, or sales literature without prior written consent in
;each case.
(define logical:boole-xor
'#(#(0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15)
#(1 0 3 2 5 4 7 6 9 8 11 10 13 12 15 14)
#(2 3 0 1 6 7 4 5 10 11 8 9 14 15 12 13)
#(3 2 1 0 7 6 5 4 11 10 9 8 15 14 13 12)
#(4 5 6 7 0 1 2 3 12 13 14 15 8 9 10 11)
#(5 4 7 6 1 0 3 2 13 12 15 14 9 8 11 10)
#(6 7 4 5 2 3 0 1 14 15 12 13 10 11 8 9)
#(7 6 5 4 3 2 1 0 15 14 13 12 11 10 9 8)
#(8 9 10 11 12 13 14 15 0 1 2 3 4 5 6 7)
#(9 8 11 10 13 12 15 14 1 0 3 2 5 4 7 6)
#(10 11 8 9 14 15 12 13 2 3 0 1 6 7 4 5)
#(11 10 9 8 15 14 13 12 3 2 1 0 7 6 5 4)
#(12 13 14 15 8 9 10 11 4 5 6 7 0 1 2 3)
#(13 12 15 14 9 8 11 10 5 4 7 6 1 0 3 2)
#(14 15 12 13 10 11 8 9 6 7 4 5 2 3 0 1)
#(15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0)))
(define logical:boole-and
'#(#(0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0)
#(0 1 0 1 0 1 0 1 0 1 0 1 0 1 0 1)
#(0 0 2 2 0 0 2 2 0 0 2 2 0 0 2 2)
#(0 1 2 3 0 1 2 3 0 1 2 3 0 1 2 3)
#(0 0 0 0 4 4 4 4 0 0 0 0 4 4 4 4)
#(0 1 0 1 4 5 4 5 0 1 0 1 4 5 4 5)
#(0 0 2 2 4 4 6 6 0 0 2 2 4 4 6 6)
#(0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7)
#(0 0 0 0 0 0 0 0 8 8 8 8 8 8 8 8)
#(0 1 0 1 0 1 0 1 8 9 8 9 8 9 8 9)
#(0 0 2 2 0 0 2 2 8 8 10 10 8 8 10 10)
#(0 1 2 3 0 1 2 3 8 9 10 11 8 9 10 11)
#(0 0 0 0 4 4 4 4 8 8 8 8 12 12 12 12)
#(0 1 0 1 4 5 4 5 8 9 8 9 12 13 12 13)
#(0 0 2 2 4 4 6 6 8 8 10 10 12 12 14 14)
#(0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15)))
(define (logical:ash-4 x)
(if (negative? x)
(+ -1 (quotient (+ 1 x) 16))
(quotient x 16)))
(define (logical:reduce op4 ident)
(lambda args
(do ((res ident (op4 res (car rgs) 1 0))
(rgs args (cdr rgs)))
((null? rgs) res))))
;@
(define logand
(letrec
((lgand
(lambda (n2 n1 scl acc)
(cond ((= n1 n2) (+ acc (* scl n1)))
((zero? n2) acc)
((zero? n1) acc)
(else (lgand (logical:ash-4 n2)
(logical:ash-4 n1)
(* 16 scl)
(+ (* (vector-ref (vector-ref logical:boole-and
(modulo n1 16))
(modulo n2 16))
scl)
acc)))))))
(logical:reduce lgand -1)))
;@
(define logior
(letrec
((lgior
(lambda (n2 n1 scl acc)
(cond ((= n1 n2) (+ acc (* scl n1)))
((zero? n2) (+ acc (* scl n1)))
((zero? n1) (+ acc (* scl n2)))
(else (lgior (logical:ash-4 n2)
(logical:ash-4 n1)
(* 16 scl)
(+ (* (- 15 (vector-ref
(vector-ref logical:boole-and
(- 15 (modulo n1 16)))
(- 15 (modulo n2 16))))
scl)
acc)))))))
(logical:reduce lgior 0)))
;@
(define logxor
(letrec
((lgxor
(lambda (n2 n1 scl acc)
(cond ((= n1 n2) acc)
((zero? n2) (+ acc (* scl n1)))
((zero? n1) (+ acc (* scl n2)))
(else (lgxor (logical:ash-4 n2)
(logical:ash-4 n1)
(* 16 scl)
(+ (* (vector-ref (vector-ref logical:boole-xor
(modulo n1 16))
(modulo n2 16))
scl)
acc)))))))
(logical:reduce lgxor 0)))
;@
(define (lognot n) (- -1 n))
;@
(define (logtest n1 n2)
(not (zero? (logand n1 n2))))
;@
(define (logbit? index n)
(logtest (expt 2 index) n))
;@
(define (copy-bit index to bool)
(if bool
(logior to (arithmetic-shift 1 index))
(logand to (lognot (arithmetic-shift 1 index)))))
;@
(define (bitwise-if mask n0 n1)
(logior (logand mask n0)
(logand (lognot mask) n1)))
;@
(define (bit-field n start end)
(logand (lognot (ash -1 (- end start)))
(arithmetic-shift n (- start))))
;@
(define (copy-bit-field to from start end)
(bitwise-if (arithmetic-shift (lognot (ash -1 (- end start))) start)
(arithmetic-shift from start)
to))
;@
(define (rotate-bit-field n count start end)
(define width (- end start))
(set! count (modulo count width))
(let ((mask (lognot (ash -1 width))))
(define zn (logand mask (arithmetic-shift n (- start))))
(logior (arithmetic-shift
(logior (logand mask (arithmetic-shift zn count))
(arithmetic-shift zn (- count width)))
start)
(logand (lognot (ash mask start)) n))))
;@
(define (arithmetic-shift n count)
(if (negative? count)
(let ((k (expt 2 (- count))))
(if (negative? n)
(+ -1 (quotient (+ 1 n) k))
(quotient n k)))
(* (expt 2 count) n)))
;@
(define integer-length
(letrec ((intlen (lambda (n tot)
(case n
((0 -1) (+ 0 tot))
((1 -2) (+ 1 tot))
((2 3 -3 -4) (+ 2 tot))
((4 5 6 7 -5 -6 -7 -8) (+ 3 tot))
(else (intlen (logical:ash-4 n) (+ 4 tot)))))))
(lambda (n) (intlen n 0))))
;@
(define logcount
(letrec ((logcnt (lambda (n tot)
(if (zero? n)
tot
(logcnt (quotient n 16)
(+ (vector-ref
'#(0 1 1 2 1 2 2 3 1 2 2 3 2 3 3 4)
(modulo n 16))
tot))))))
(lambda (n)
(cond ((negative? n) (logcnt (lognot n) 0))
((positive? n) (logcnt n 0))
(else 0)))))
;@
(define (log2-binary-factors n)
(+ -1 (integer-length (logand n (- n)))))
(define (bit-reverse k n)
(do ((m (if (negative? n) (lognot n) n) (arithmetic-shift m -1))
(k (+ -1 k) (+ -1 k))
(rvs 0 (logior (arithmetic-shift rvs 1) (logand 1 m))))
((negative? k) (if (negative? n) (lognot rvs) rvs))))
;@
(define (reverse-bit-field n start end)
(define width (- end start))
(let ((mask (lognot (ash -1 width))))
(define zn (logand mask (arithmetic-shift n (- start))))
(logior (arithmetic-shift (bit-reverse width zn) start)
(logand (lognot (ash mask start)) n))))
;@
(define (integer->list k . len)
(if (null? len)
(do ((k k (arithmetic-shift k -1))
(lst '() (cons (odd? k) lst)))
((<= k 0) lst))
(do ((idx (+ -1 (car len)) (+ -1 idx))
(k k (arithmetic-shift k -1))
(lst '() (cons (odd? k) lst)))
((negative? idx) lst))))
;@
(define (list->integer bools)
(do ((bs bools (cdr bs))
(acc 0 (+ acc acc (if (car bs) 1 0))))
((null? bs) acc)))
(define (booleans->integer . bools)
(list->integer bools))
;;;;@ SRFI-60 aliases
(define ash arithmetic-shift)
(define bitwise-ior logior)
(define bitwise-xor logxor)
(define bitwise-and logand)
(define bitwise-not lognot)
(define bit-count logcount)
(define bit-set? logbit?)
(define any-bits-set? logtest)
(define first-set-bit log2-binary-factors)
(define bitwise-merge bitwise-if)
;;; Legacy
;;(define (logical:rotate k count len) (rotate-bit-field k count 0 len))
;;(define (logical:ones deg) (lognot (ash -1 deg)))
;;(define integer-expt expt) ; legacy name
This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to the Scheme Request For Implementation process or editors, except as needed for the purpose of developing SRFIs in which case the procedures for copyrights defined in the SRFI process must be followed, or as required to translate it into languages other than English.
The limited permissions granted above are perpetual and will not be revoked by the authors or their successors or assigns.
This document and the information contained herein is provided on an "AS IS" basis and THE AUTHOR AND THE SRFI EDITORS DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.