Manual page for bitwise-bit-field(3scm)

bitwise-bit-field, fxbit-field - bit field extract

LIBRARY

(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

Returns the number represented by the bits at the positions from start (inclusive) to end (exclusive), which is the result of the following computation:

;; 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))

RETURN VALUES

Returns a single exact integer object.

EXAMPLES

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

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

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.

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.

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

Markup created by unroff 1.0sc, March 04, 2023.