Byte Manipulation Functions

Several functions are provided for dealing with an arbitrary-width ﬁeld of contiguous bits appearing anywhere in an integer. Such a contiguous set of bits is called a byte. Here the term byte does not imply some ﬁxed number of bits (such as eight), rather a ﬁeld of arbitrary and user-speciﬁable width.

The byte-manipulation functions use objects called byte speciﬁers to designate a speciﬁc byte position within an integer. The representation of a byte speciﬁer is implementation-dependent; in particular, it may or may not be a number. It is suﬃcient to know that the function byte will construct one, and that the byte-manipulation functions will accept them. The function byte accepts two integers representing the position and size of the byte and returns a byte speciﬁer. Such a speciﬁer designates a byte whose width is size and whose bits have weights 2^{position+size−1} through 2^position.

[Function] byte size position

byte takes two integers representing the size and position of a byte and returns a byte speciﬁer suitable for use as an argument to byte-manipulation functions.

[Function] byte-size bytespec
[Function] byte-position bytespec

Given a byte speciﬁer, byte-size returns the size speciﬁed as an integer; byte-position similarly returns the position. For example:

(byte-size (byte j k)) ≡ j (byte-position (byte j k)) ≡ k

[Function] ldb bytespec integer

bytespec speciﬁes a byte of integer to be extracted. The result is returned as a non-negative integer. For example:

(logbitp j (ldb (byte s p) n)) ≡ (and (< j s) (logbitp (+ j p) n))

The name of the function ldb means “load byte.”

If the argument integer is speciﬁed by a form that is a place form acceptable to setf, then setf may be used with ldb to modify a byte within the integer that is stored in that place. The eﬀect is to perform a dpb operation and then store the result back into the place.

[Function] ldb-test bytespec integer

ldb-test is a predicate that is true if any of the bits designated by the byte speciﬁer bytespec are 1’s in integer; that is, it is true if the designated ﬁeld is non-zero.

(ldb-test bytespec n) ≡ (not (zerop (ldb bytespec n)))

[Function] mask-ﬁeld bytespec integer

This is similar to ldb; however, the result contains the speciﬁed byte of integer in the position speciﬁed by bytespec, rather than in position 0 as with ldb. The result therefore agrees with integer in the byte speciﬁed but has zero-bits everywhere else. For example:

(ldb bs (mask-ﬁeld bs n)) ≡ (ldb bs n) (logbitp j (mask-ﬁeld (byte s p) n)) ≡ (and (>= j p) (< j (+ p s)) (logbitp j n)) (mask-ﬁeld bs n) ≡ (logand n (dpb -1 bs 0))

If the argument integer is speciﬁed by a form that is a place form acceptable to setf, then setf may be used with mask-ﬁeld to modify a byte within the integer that is stored in that place. The eﬀect is to perform a deposit-ﬁeld operation and then store the result back into the place.

[Function] dpb newbyte bytespec integer

This returns a number that is the same as integer except in the bits speciﬁed by bytespec. Let s be the size speciﬁed by bytespec; then the low s bits of newbyte appear in the result in the byte speciﬁed by bytespec. The integer newbyte is therefore interpreted as being right-justiﬁed, as if it were the result of ldb. For example:

(logbitp j (dpb m (byte s p) n)) ≡ (if (and (>= j p) (< j (+ p s))) (logbitp (- j p) m) (logbitp j n))

The name of the function dpb means “deposit byte.”

[Function] deposit-ﬁeld newbyte bytespec integer

This function is to mask-ﬁeld as dpb is to ldb. The result is an integer that contains the bits of newbyte within the byte speciﬁed by bytespec, and elsewhere contains the bits of integer. For example:

(logbitp j (deposit-ﬁeld m (byte s p) n)) ≡ (if (and (>= j p) (< j (+ p s))) (logbitp j m) (logbitp j n))

__________________________________________________________________________

Implementation note: If the bytespec is a constant, one may of course construct, at compile time, an equivalent mask m, for example by computing (deposit-ﬁeld -1 bytespec 0). Given this mask m, one may then compute

(deposit-ﬁeld newbyte bytespec integer)

by computing

(logior (logand newbyte m) (logand integer (lognot m)))

where the result of (lognot m) can of course also be computed at compile time. However, the following expression may also be used and may require fewer temporary registers in some situations:

(logxor integer (logand m (logxor integer newbyte)))

A related, though possibly less useful, trick is that

(let ((z (logand (logxor x y) m))) (setq x (logxor z x)) (setq y (logxor z y)))

interchanges those bits of x and y for which the mask m is 1, and leaves alone those bits of x and y for which m is 0.

__________________________________________________________________________

12.8 Byte Manipulation Functions