bitwise-not(3scm)

✨ NAME ✨

bitwise-not — bitwise negation, one's complement. This page is bitwise-not(3scm) from the Scheme Programmer's Manual, and it's literally here to flip bits for you. bestie, you're gonna slay this. 💅

📚 LIBRARY 📚

Import it like this, depending on your flavor:

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

🪄 SYNOPSIS 🪄

(bitwise-not ei)
(fxnot fx)

💖 DESCRIPTION 💖

bitwise-not 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. iykyk.

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). slay, speed queen. ⚡

🎁 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. that's the whole vibe.

🌈 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. periodt.

🚨 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)).

bestie, that second one is the "fixnum said no" moment: (fxnot (least-fixnum)) can raise it because the result is not representable as a fixnum. 🫠

👀 SEE ALSO 👀

fxnot(3scm) — go check it out, bestie. 💜

📜 STANDARDS 📜

R6RS, SRFI-60, SRFI-151. the standards said yes.

🕰️ 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. a whole timeline moment. 🦋

💖 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/. credit where it's due. 🫶

💀 BUGS 💀

The original BUGS section is empty — literally nothing listed here, bestie. So there's nothing to report. 💀

---

bye bestie 💖 — this page is from the Scheme Programmer's Manual / scheme-manpages project, dated 2020-10-07, and it's bitwise-not(3scm). mwah 💋