chickadee » srfi-60

SRFI 60: Integers as Bits

This egg provides the SRFI 60 bitwise library, implemented as a very thin wrapper on top of bitwise-utils. Every form that appears here can be found in bitwise-utils under a different name, and srfi-151 (the successor to SRFI 60) provides many operations not found in either egg. There's not much reason to use this library.

SRFI description

This page is intended to document the forms provided by this egg. For a full description of SRFI 60, see the SRFI document.

Specification

Bitwise Operations

logand n1 ...procedure
bitwise-and n1 ...procedure

Returns the integer which is the bit-wise AND of the integer arguments.

Example:

(number->string (logand #b1100 #b1010) 2)
    ; => "1000"
logior n1 ...procedure
bitwise-ior n1 ...procedure

Returns the integer which is the bit-wise OR of the integer arguments.

Example:

(number->string (logior #b1100 #b1010) 2)
    ; => "1110"
logxor n1 ...procedure
bitwise-xor n1 ...procedure

Returns the integer which is the bit-wise XOR of the integer arguments.

Example:

(number->string (logxor #b1100 #b1010) 2)
    ; => "110"
lognot nprocedure
bitwise-not nprocedure

Returns the integer which is the one's-complement of the integer argument.

Example:

(number->string (lognot #b10000000) 2)
    ; => "-10000001"
(number->string (lognot #b0) 2)
    ; => "-1"
bitwise-if mask n0 n1procedure
bitwise-merge mask n0 n1procedure

Returns an integer composed of some bits from integer n0 and some from integer n1. A bit of the result is taken from n0 if the corresponding bit of integer mask is 1 and from n1 if that bit of mask is 0.

logtest j kprocedure
any-bits-set? j kprocedure

Example:

(logtest j k) == (not (zero? (logand j k)))

(logtest #b0100 #b1011) ; => #f
(logtest #b0100 #b0111) ; => #t

Integer Properties

logcount nprocedure
bit-count nprocedure

Returns the number of bits in integer n. If integer is positive, the 1-bits in its binary representation are counted. If negative, the 0-bits in its two's-complement binary representation are counted. If 0, 0 is returned.

Example:

(logcount #b10101010)
   ; => 4
(logcount 0)
   ; => 0
(logcount -2)
   ; => 1
integer-length nprocedure

Returns the number of bits neccessary to represent n.

Example:

(integer-length #b10101010)
   ; => 8
(integer-length 0)
   ; => 0
(integer-length #b1111)
   ; => 4
log2-binary-factors nprocedure
first-set-bit nprocedure

Returns the number of factors of two of integer n. This value is also the bit-index of the least-significant 1-bit in n.

Bit Within Word

logbit? index nprocedure
bit-set? index nprocedure

Example:

(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
copy-bit index from bitprocedure

Returns an integer the same as from except in the indexth bit, which is 1 if bit is #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"

Field of Bits

bit-field n start endprocedure

Returns the integer composed of the start (inclusive) through end (exclusive) bits of n. The startth bit becomes the 0-th bit in the result.

Example:

(number->string (bit-field #b1101101010 0 4) 2)
   ; => "1010"
(number->string (bit-field #b1101101010 4 9) 2)
   ; => "10110"
copy-bit-field to from start endprocedure

Returns an integer the same as to except possibly in the start (inclusive) through end (exclusive) bits, which are the same as those of from. The 0-th bit of from becomes the startth bit of the result.

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"
ash n countprocedure
arithmetic-shift n countprocedure

Returns an integer equivalent to (inexact->exact (floor (* n (expt 2 count)))).

Example:

(number->string (ash #b1 3) 2)
   ; => "1000"
(number->string (ash #b1010 -1) 2)
   ; => "101"
rotate-bit-field n count start endprocedure

Returns n with the bit-field from start to end cyclically permuted by count bits towards high-order.

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"
reverse-bit-field n start endprocedure

Returns n with the order of bits start to end reversed.

Example:

(number->string (reverse-bit-field #xa7 0 8) 16)
   ; => "e5"

Bits as Booleans

integer->list k lenprocedure
integer->list kprocedure

integer->list returns a list of len booleans corresponding to each bit of the non-negative integer k. #t is coded for each 1; #f for 0. The len argument defaults to (integer-length k)

list->integer listprocedure

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.

booleans->integer bool1 ...procedure

Returns the integer coded by the bool1 ... arguments.

About this egg

Author

Aubrey Jaffer

Originally ported to hygienic Chicken 3 with test suite by Peter Danenberg. Ported to Chicken 5 by Sergey Goldgaber.

Maintainer

Wolfgang Corcoran-Mathe

Contact: wcm at sigwinch dot xyzzy minus the zy

Repository

GitHub

Version history

0.7.1
Change maintainer, tidy tests and wiki page.
0.7
Registered the srfi-60 feature, linked to source code
0.6
Replaced srfi-60 implementation with that from bitwise-utils
0.5
Using (chicken bitwise) procedures, where possible
0.4
Ported to Chicken 5
0.3
release version 0.3
0.2
adopting trunk/tags directory layout. Tagging version 0.2.

License

Copyright (C) Aubrey Jaffer (2004, 2005). All Rights Reserved.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Contents »