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.