Common Lisp the Language, 2nd Edition     Next: Fill Pointers Up: Arrays Previous: Array Information

# 17.4. Functions on Arrays of Bits

The functions described in this section operate only on arrays of bits, that is, specialized arrays whose elements are all 0 or 1.

[Function]
bit bit-array &rest subscripts
sbit simple-bit-array &rest subscripts

bit is exactly like aref but requires an array of bits, that is, one of type (array bit). The result will always be 0 or 1. sbit is like bit but additionally requires that the first argument be a simple array (see section 2.5). Note that bit and sbit, unlike char and schar, allow the first argument to be an array of any rank.

setf may be used with bit or sbit to destructively replace a bit-array element with a new value.

bit and sbit are identical to aref except for the more specific type requirements on the first argument. In some implementations of Common Lisp, bit may be faster than aref in situations where it is applicable, and sbit may similarly be faster than bit.

[Function]

```bit-and bit-array1 bit-array2 &optional result-bit-array
bit-ior bit-array1 bit-array2 &optional result-bit-array
bit-xor bit-array1 bit-array2 &optional result-bit-array
bit-eqv bit-array1 bit-array2 &optional result-bit-array
bit-nand bit-array1 bit-array2 &optional result-bit-array
bit-nor bit-array1 bit-array2 &optional result-bit-array
bit-andc1 bit-array1 bit-array2 &optional result-bit-array
bit-andc2 bit-array1 bit-array2 &optional result-bit-array
bit-orc1 bit-array1 bit-array2 &optional result-bit-array
bit-orc2 bit-array1  bit-array2 &optional result-bit-array
```

These functions perform bit-wise logical operations on bit-arrays. All of the arguments to any of these functions must be bit-arrays of the same rank and dimensions. The result is a bit-array of matching rank and dimensions, such that any given bit of the result is produced by operating on corresponding bits from each of the arguments.

If the third argument is nil or omitted, a new array is created to contain the result. If the third argument is a bit-array, the result is destructively placed into that array. If the third argument is t, then the first argument is also used as the third argument; that is, the result is placed back in the first array.

The following table indicates what the result bit is for each operation as a function of the two corresponding argument bits.

```argument1  0  0  1  1
argument2  0  1  0  1  Operation name
------------------------------------------------------------
bit-and    0  0  0  1  and
bit-ior    0  1  1  1  inclusive or
bit-xor    0  1  1  0  exclusive or
bit-eqv    1  0  0  1  equivalence (exclusive nor)
bit-nand   1  1  1  0  not-and
bit-nor    1  0  0  0  not-or
bit-andc1  0  1  0  0  and complement of argument1 with argument2
bit-andc2  0  0  1  0  and argument1 with complement of argument2
bit-orc1   1  1  0  1  or complement of argument1 with argument2
bit-orc2   1  0  1  1  or argument1 with complement of argument2
------------------------------------------------------------
```

For example:

```(bit-and #*1100 #*1010) => #*1000
(bit-xor #*1100 #*1010) => #*0110
(bit-andc1 #*1100 #*1010) => #*0100
```

See logand and related functions.

[Function]
bit-not bit-array &optional result-bit-array

The first argument must be an array of bits. A bit-array of matching rank and dimensions is returned that contains a copy of the argument with all the bits inverted. See lognot.

If the second argument is nil or omitted, a new array is created to contain the result. If the second argument is a bit-array, the result is destructively placed into that array. If the second argument is t, then the first argument is also used as the second argument; that is, the result is placed back in the first array.     Next: Fill Pointers Up: Arrays Previous: Array Information

AI.Repository@cs.cmu.edu