Scheme Programmer's Manual

NAME

bitwise-and, bitwise-ior, bitwise-xor, fxand, fxior, fxxor - bitwise arithmetic

LIBRARY

(import (rnrs))                     ;R6RS
(import (rnrs arithmetic bitwise))  ;R6RS
(import (rnrs arithmetic fixnums))  ;R6RS

SYNOPSIS

(bitwise-and ei ...)
(bitwise-ior ei ...)
(bitwise-xor ei ...)
(fxand fx ...)
(fxior fx ...)
(fxxor fx ...)

DESCRIPTION

These procedures return the exact integer object that is the bitwise "and", "inclusive or", or "exclusive or" of the two's complement representations of their arguments. If they are passed only one argument, they return that argument. If they are passed no arguments, they return the integer object (either −1 or 0) that acts as identity for the operation.

The procedures whose names begin with fx take fixnums(7) as arguments and only return fixnums.

RETURN VALUES

A single exact integer object as per the description.

EXAMPLES

;; These examples use binary notation for clarity.

;; bitwise-and preserves the 1-bits that are in common, ;; which is often called "masking". (bitwise-and #b10101010 #b00001111) => #b1010

;; bitwise-xor can be used to flip bits: (bitwise-xor #b10101010 #b11111111) => #b01010101

;; bitwise-ior can be used to set bits: (bitwise-ior #b10000000 #b00000011) => #b10000011

;; Negative numbers notionally have all bits set to the ;; left of the most significant zero bit. (bitwise-and #b10101010 #b-10000) => #b10100000

The Scheme programmer who is interested in bitwise arithmetic should explore HAKMEM (AI Memo 239).

RATIONALE

These procedures are efficiently implemented on binary computers and are useful in numerous applications, including: hashing, cryptography, error correcting codes, digital logic, binary data structures and network protocols.

COMPATIBILITY

These procedures are compatible with the equivalent bitwise operators for signed integers in other languages.

ERRORS

These procedures can raise exceptions with the following condition types:
&assertion (R6RS)
An argument was outside its domain.

SEE ALSO

bitwise-not(3)

STANDARDS

R6RS, SRFI-60, SRFI-151

HISTORY

These procedures mirror the CPU instructions for bitwise arithmetic in binary computers, but they are extended to support arbitrarily large integers. They appear in the names logand, logior, and logxor in Maclisp.

AUTHORS

This page is part of the scheme-manpages project. It includes materials from the RnRS documents. More information can be found at

BUGS

While there are no known bugs in the common implementations of these procedures, they are tricky to implement correctly with bignums, and bugs have shown up in the past. Established bignum libraries rarely provide them, so Scheme implementers are on their own. The difficult part is handling negative integers. The lazy implementer can use the following identities from "Hackers Delight".

;; ~ is bitwise-not ;; | is bitwise-ior ;; & is bitwise-and ;; ^ is bitwise-xor a & b == ~(~a | ~b) a & b == a - (a & ~b) a ^ b == ~a ^ ~b a ^ b == ~(a & ~b) a | b == ~(~a & ~b) a | b == (a & ~b) + b

Index

NAME
LIBRARY
SYNOPSIS
DESCRIPTION
RETURN VALUES
EXAMPLES
RATIONALE
COMPATIBILITY
ERRORS
SEE ALSO
STANDARDS
HISTORY
AUTHORS
BUGS
Return to Main Contents