bitwise-not - bitwise negation, one's complement

LIBRARY

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

SYNOPSIS

(bitwise-not ei)
(fxnot fx)

DESCRIPTION

Returns the bitwise negation of the exact integer ei.

If Scheme integers were unsigned (i.e. only positive) then this could be thought of as negating every bit in the integer. There is however a subtle difference, having to do with the sign of the returned integer, that makes such a description not quite accurate.

The fxnot procedure takes a fixnum as an argument and always returns a fixnum (but see the ERRORS section below).

IMPLEMENTATION NOTES

GNU Guile
In GNU Guile this procedure is faster than the equivalent fixnum-only procedure fxnot(3scm).

RETURN VALUES

Returns the exact integer object whose two's complement representation is the one's complement of the two's complement representation of ei.

EXAMPLES

;; There are no bits set in zero, so the returned value
;; has all bits set. Negative numbers notionally have all
;; bits set to the left of the most significant zero bit.
(number->string (bitwise-not #b0) 2)
  => "-1"

;; Visually, it may not be obvious that the returned value
;; is the one's-complement:
(number->string (bitwise-not #b11110000) 2)
  => "-11110001"

;; Masking the value to the desired bit-width will reveal
;; that the value is correct:
(number->string
 (bitwise-and #xFFFF         ; treat as 16-bit unsigned
  (bitwise-not #b11110000)) 2)
     => "1111111100001111"

;; The complement of the complement is the original number:
(bitwise-not -43) => 42
(bitwise-not 42) => -43

RATIONALE

bitwise-not is one of the fundamental bitwise operators.

ERRORS

This procedure can raise exceptions with the following condition types:
&assertion (R6RS)
The wrong number of arguments was passed or an argument was outside its domain.
&implementation-restriction (R6RS)
The result is not representable as a fixnum. Raised for (fxnot (least-fixnum)).

SEE ALSO

fxnot(3scm)

STANDARDS

R6RS, SRFI-60, SRFI-151

HISTORY

The history of bitwise complement can likely be traced to the first binary computers that provided a NOT instruction, or to the invention of binary arithmetic. In Scheme it appeared relatively late with the (withdrawn) SRFI-33 in 2003, and would not appear in an RnRS document until R6RS in 2007.

AUTHORS

This page is part of the scheme-manpages project. It includes materials from the RnRS documents. More information can be found at https://github.com/schemedoc/manpages/.

BUGS


Markup created by unroff 1.0sc,    March 04, 2023.