bitwise-and(3scm)

🌸 NAME 🌸

okay bestie, welcome to bitwise-and(3scm) from the Scheme Programmer's Manual — this is the bitwise arithmetic page and it's lowkey iconic 💅✨

• bitwise-and, bitwise-ior, bitwise-xor, fxand, fxior, fxxor — bitwise arithmetic 🎀

---

📚 LIBRARY 📚

these are the imports you need, depending on which flavor you're living in:

(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 💖

okay so 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. no cap. if you pass only one argument, they return that argument — one and done. if you pass no arguments, they return the integer object (either −1 or 0) that acts as identity for the operation. slay 🫶

the procedures whose names begin with fx take fixnums(7scm) as arguments and only return fixnums. so keep it fixnum-shaped, bestie 💜

---

🦋 RETURN VALUES 🦋

a single exact integer object as per the description. that's the whole vibe ✨

---

🔥 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

if you're a Scheme programmer who's interested in bitwise arithmetic, you should 100% 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. it's giving essential toolbox energy 🌈💅

---

🌸 COMPATIBILITY 🌸

these procedures are compatible with the equivalent bitwise operators for signed integers in other languages. iykyk 💖

---

😭 ERRORS 😭

these procedures can raise exceptions with the following condition types:

• &assertion (R6RS) — an argument was outside its domain. rude, but valid 💀

---

🎀 SEE ALSO 🎀

• bitwise-not(3scm) — go check it out, bestie 🫶

---

⭐ STANDARDS ⭐

R6RS, SRFI-60, SRFI-151. periodt ✨

---

💜 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. history lesson but make it cute 🎀

---

👑 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/. love that for us 💖

---

💀 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

---

and that's the page, bestie 💖 — source/version bitwise-and(3scm), dated 2020-10-18. periodt 🎀✨