Skip to main content

mask-field

mask-field Accessor

Syntax:

mask-field bytespec integer ! masked-integer

(setf (mask-field bytespec place**)** new-masked-integer**)**

Arguments and Values:

bytespec—a byte specifier .

integer—an integer .

masked-integer, new-masked-integer—a non-negative integer .

Description:

mask-field performs a “mask” operation on integer. It returns an integer that has the same bits as integer in the byte specified by bytespec, but that has zero-bits everywhere else.

setf may be used with mask-field to modify a byte within the integer that is stored in a given place. The e↵ect is to perform a deposit-field operation and then store the result back into the place.

Examples:

(mask-field (byte 1 5) -1) *!* 32 
(setq a 15) *!* 15 
(mask-field (byte 2 0) a) *!* 3 
a *!* 15 
(setf (mask-field (byte 2 0) a) 1) *!* 1 
a *!* 13

See Also:

byte, ldb

Notes:

(ldb bs (mask-field bs n)) ⌘ (ldb bs n)

(logbitp j (mask-field (byte s p) n))

⌘ (and (>= j p) (< j s) (logbitp j n))

(mask-field bs n) ⌘ (logand n (dpb -1 bs 0))

Expanded Reference: mask-field​

Basic masking​

mask-field returns an integer with the same bits as the input within the specified byte, and zero bits everywhere else. Unlike ldb, the result bits stay at their original position.

(mask-field (byte 1 5) -1)
=> 32
(mask-field (byte 2 0) 15)
=> 3
(mask-field (byte 4 0) #xFF)
=> 15
(mask-field (byte 4 4) #xFF)
=> 240

Difference from ldb​

ldb right-justifies the extracted bits; mask-field keeps them at their original position.

;; ldb extracts and right-justifies
(ldb (byte 4 4) #xAB)
=> 10

;; mask-field keeps bits in position
(mask-field (byte 4 4) #xAB)
=> 160

setf with mask-field​

mask-field is a setf-able accessor. Setting it performs a deposit-field operation.

(let ((a 15))
  (setf (mask-field (byte 2 0) a) 1)
  a)
=> 13

Masking preserves the byte for ldb​

The identity (ldb bs (mask-field bs n)) equals (ldb bs n).

(let ((bs (byte 4 4))
      (n #xABCD))
  (= (ldb bs (mask-field bs n))
     (ldb bs n)))
=> T

Equivalence to logand with a mask​

mask-field is equivalent to ANDing with a mask that has ones only in the specified byte.

(let ((bs (byte 4 4)))
  (= (mask-field bs #xABCD)
     (logand #xABCD (dpb -1 bs 0))))
=> T