bitwise-...it-field(3scm)

🌸 NAME 🌸

okay bestie, meet bitwise-rotate-bit-field and fxrotate-bit-field — the bitwise rotate left duo. This is their page from the Scheme Programmer's Manual, and the manual name is bitwise-...it-field(3scm) (yes, the truncated name is giving classic manpage energy 💅).

📚 LIBRARY 📚

These two live in the R6RS imports, and the import lines are literally:

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

✨ SYNOPSIS ✨

(bitwise-rotate-bit-field n start end count)
(fxrotate-bit-field n start end count)

💖 DESCRIPTION 💖

It returns the result of cyclically permuting in n the bits at positions from start (inclusive) to end (exclusive) by bits towards the more significant bits. That's the rotation vibe, periodt. 🌀

🛠️ IMPLEMENTATION NOTES 🛠️

The following are reference implementations from R6RS. Not me dropping the actual recipe, but yes bestie, here's the code:

;; bitwise-rotate-bit-field
(let ((width (- end start)))
  (if (positive? width)
      (let* ((count (mod count width))
             (field0
               (bitwise-bit-field n start end))
             (field1 (bitwise-arithmetic-shift-left
                       field0 count))
             (field2 (bitwise-arithmetic-shift-right
                       field0
                       (- width count)))
             (field (bitwise-ior field1 field2)))
        (bitwise-copy-bit-field n start end field))
      n))

;; fxrotate-bit-field
(let ((width (fx- end start)))
  (fxcopy-bit-field n start end
    (fxior
      (fxarithmetic-shift-left
        (fxbit-field n start (fx- end count))
        count)
      (fxarithmetic-shift-right
        (fxbit-field n start end)
        (fx- width count)))))

🎁 RETURN VALUES 🎁

Returns a single value; an exact integer. One value, exact integer, no extra drama. 💖

🌟 EXAMPLES 🌟

(fxrotate-bit-field #x1234 4 12 4)  =>  #x1324

🔐 APPLICATION USAGE 🔐

Bitwise rotation is a common operation in cryptography. So yes, this is lowkey crypto-core. 🔥

🧩 COMPATIBILITY 🧩

These procedures are unique to R6RS. Similar alternatives can be found in SRFI-60 and SRFI-151. Not the same vibe, but cousins. 🫶

💀 ERRORS 💀

These procedures can raise exceptions with the following condition types:

• &assertion (R6RS) — The wrong number of arguments was passed or an argument was outside its domain. In particular, all arguments must be exact integers, start, end and count must be non-negative, and start must be less than or equal to end.

For the fixnum variant there are further restrictions. All arguments must be fixnums, and start, end and count must be less than the implementation's fixnum width, and count must be less than or equal to end-start.

👀 SEE ALSO 👀

• bitwise-rotate-bit-field(3scm)
• bitwise-arithmetic-shift(3scm)
• bitwise-copy-bit-field(3scm)

📏 STANDARDS 📏

R6RS. periodt. 🎀

🕰️ HISTORY 🕰️

Many processor instruction set architectures have an integer rotate instruction. R6RS was the first Scheme report to standardize this operation. Previously SRFI-60 had slightly different bit-field-rotate procedure. Early Scheme running on MacLISP had access to the rot procedure that rotated a whole 36-bit fixnum by some amount. History ate, honestly. 👑

👑 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/.

okay bestie, that's the whole page — signing off from bitwise-...it-field(3scm) on 2023-02-12, straight from the Scheme Programmer's Manual 💖✨🦋