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

✨ NAME ✨

okay bestie, welcome to the bitwise-...it-field(3scm) page from the Scheme Programmer's Manual — main character energy fr fr. This page is all about bitwise-copy-bit-field and fxcopy-bit-field, aka copy a bitfield from one integer onto another. No cap, that's the whole name section, and it ate. 💅

🫶 LIBRARY 🫶

import these depending on your flavor, bestie:

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

💅 SYNOPSIS 💅

the signatures, exactly as they are, periodt:

       (bitwise-copy-bit-field to start end from)
       (fxcopy-bit-field to start end from)

🦋 DESCRIPTION 🦋

Returns the result of replacing in to the bits at positions from start (inclusive) to end (exclusive) by the bits in from from position 0 (inclusive) to position end−start (exclusive). Literally that's the tea, and it's giving bitfield glow-up. ✨

🧚 IMPLEMENTATION NOTES 🧚

R6RS handed us these reference implementations, and they're iconic:

       ; bitwise-copy-bit-field
       (let* ((mask1
               (bitwise-arithmetic-shift-left -1 start))
              (mask2
               (bitwise-not
                (bitwise-arithmetic-shift-left -1 end)))
              (mask (bitwise-and mask1 mask2)))
         (bitwise-if mask
                     (bitwise-arithmetic-shift-left from start)
                     to))

       ; fxcopy-bit-field
       (let* ((mask1 (fxarithmetic-shift-left -1 start))
              (mask2 (fxnot
                      (fxarithmetic-shift-left -1 end)))
              (mask (fxand mask1 mask2))
              (mask3 (fxnot (fxarithmetic-shift-left
                              -1 (- end start)))))
         (fxif mask
               (fxarithmetic-shift-left (fxand from mask3)
                                        start)
               to))

🌸 RETURN VALUES 🌸

Returns a single value; an exact integer. The fixnum variant returns a fixnum. slay. 💖

🍓 EXAMPLES 🍓

       (fxcopy-bit-field #b0000001 2 5 #b1111000)
                 => 1
       (fxcopy-bit-field #b0000001 2 5 #b0001111)
                 => 29
       (fxcopy-bit-field #b0001111 2 5 #b0001111)
                 => 31

💀 COMPATIBILITY 💀

This procedure is unique to R6RS. iykyk. 🫶

🚨 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. In particular, start and end must be non-negative, and start must be less than or equal to end.

The fixnum variant furthermore requires that all arguments are fixnums and that start and end are less than (fixnum-width). not me forgetting the fixnum-width vibe check 😭

🔥 SEE ALSO 🔥

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

👑 STANDARDS 👑

R6RS. periodt. 👑

🌈 HISTORY 🌈

These procedures first appeared in R6RS. There is a similar procedure in SRFI-60 that uses a different argument order, copy-bit-field. lowkey iconic lore. 🦋

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

---

cute sign-off bestie: bitwise-...it-field(3scm) • 2023-02-13 — that's the footer source/version and date, and yes she's iconic 🫶💖