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