bitwise-bit-field(3scm)

📦 version 0-unstable-2024-02, in nixpkgs unstable

💅 bitwise-bit-field — the scheme programmer's manual page, but make it cute

okay bestie, so this is bitwise-bit-field and fxbit-field from the Scheme Programmer's Manual, and honestly? these two are little scissors for integers. they snip out a chunk of bits and hand it to you like a lil gift 🎀

✨ NAME ✨

bitwise-bit-field, fxbit-field — bit field extract 🧚

📚 LIBRARY 📚

you can import these bad boys from three different places, choose ur fighter:

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

✨ SYNOPSIS ✨

(bitwise-bit-field ei start end)
(fxbit-field fx start end)

💖 DESCRIPTION 💖

So what it does is: it returns the number represented by the bits at the positions from start (inclusive!) to end (exclusive!), which is literally the result of the following computation. no cap, this is the exact definition:

;; bitwise-bit-field
(let ((mask (bitwise-not
             (bitwise-arithmetic-shift-left -1 end))))
  (bitwise-arithmetic-shift-right (bitwise-and ei mask)
                                  start))

;; fxbit-field
(let ((mask (fxnot
             (fxarithmetic-shift-left -1 end))))
  (fxarithmetic-shift-right (fxand fx mask)
                            start))

like, it builds a mask, ANDs it, shifts it, done. iconic behaviour honestly 🔥

🌸 RETURN VALUES 🌸

Returns a single exact integer object. one (1) exact integer. that's it. that's the return value 💜

🦋 EXAMPLES 🦋

watch it work, bestie:

(fxbit-field #b10101111 4 8)
          => #b1010

(fxbit-field #b10101111 0 4)
          => #b1111

ate and left no crumbs ✨

👑 APPLICATION USAGE 👑

The operation implemented by these procedures shows up when several fields are encoded in a single integer. A typical example is the code in a Scheme implementation that parses binary IEEE 754 floating point. This pattern also appears often in binary file formats, network protocols, machine code, encryption and much more.

so like… if you're ever decoding a float by hand or staring at a network packet like 👁️👄👁️ — this is the vibe. iykyk.

🌈 COMPATIBILITY 🌈

These procedures are new in R6RS. 🆕

SRFI-151 has the generic procedure under the name bit-field.

💀 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. The arguments start and end must be non-negative and start must be less than or equal to end. The fxbit-field procedure requires that all arguments are fixnums.
ok so fr fr: give it bad numbers and it will complain. start ≤ end, both non-negative, and fxbit-field is picky — everything has to be a fixnum. no exceptions… well, except the exceptions. 😭

🫶 SEE ALSO 🫶

⭐ STANDARDS ⭐

R6RS

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

k bye bestie!! this page is from the scheme-manpages project, dated 2021-03-11 — go read more at the url above, mwah 💋💖✨

2021-03-11 · bitwise-bit-field(3scm) · slay 🌸

📦 where this page comes from