bitlib documentation

NAME

da.bitlib.doc - bitwise operations library

SYNOPSIS

.bitnot - two's complement bitwise NOT

Input parameters:
S[0]: integer.
Return value:
S[0]: integer, bitwise NOT of input.
.bitand - two's complement bitwise AND

Input parameters:
S[0], S[1]: integer.
Return value:
S[0]: integer, bitwise AND of inputs.
.bitor - two's complement bitwise OR

Input parameters:
S[0], S[1]: integer.
Return value:
S[0]: integer, bitwise OR of inputs.
.bitxor - two's complement bitwise exclusive OR

Input parameters:
S[0], S[1]: integer.
Return value:
S[0]: integer, bitwise exclusive OR of inputs.
.bit? - is a bit set?

Input parameters:
S[1]: integer.
S[0]: integer in range 0-31 specifying bit to test.
Return value:
S[0]: integer, nonzero if the bit is set, 0 otherwise.
.bitset - set a bit

Input parameters:
S[1]: integer.
S[0]: integer in range 0-31 specifying bit to set.
Return value:
S[0]: integer, the number on S[1] with the specified bit set to 1.
.bitclear - clear a bit

Input parameters:
S[1]: integer.
S[0]: integer in range 0-31 specifying bit to clear.
Return value:
S[0]: integer, the number on S[1] with the specified bit set to 0.
.bitpow2 - value of bit

Input parameters:
S[0]: integer in range 0-31.
Return value:
S[0]: integer, the value of the bit, equal to 2^n.

DESCRIPTION

bitlib is a group of related functions which perform bitwise operations on integers as if they were 32-bit signed two's complement numbers. All functions can be called using the macros given in the synopsis. The functions can be divided into two types:

Bitwise logical functions

The four functions .bitnot, .bitand, .bitor and .bitxor perform bitwise operations on integers. They perform the given action on each of the bits in the integers according to the following truth tables:

        .bitnot | 0 | 1 |              .bitand | 0 | 1 |
        --------+---+---+              --------+---+---+
                | 1 | 0 |                    0 | 0 | 0 |
        --------+---+---+                    --+---+---+
                                             1 | 0 | 1 |
                                       --------+---+---+

        .bitor  | 0 | 1 |              .bitxor | 0 | 1 |
        --------+---+---+              --------+---+---+
              0 | 0 | 1 |                    0 | 0 | 1 |
              --+---+---+                    --+---+---+
              1 | 1 | 1 |                    1 | 1 | 0 |
        --------+---+---+              --------+---+---+

Note that bit 31, the most significant bit, is the sign bit, so if it is set the corresponding integer will be negative.

Single-bit functions

The three functions .bit?, .bitset and .bitclear test, set or clear a specified bit in an integer. While they can be (and are) written in terms of the bitwise functions, it is often easier to think in terms of bit numbers.

Bits are numbered from 0 to 31, with 0 being the least significant and 31 being the signed, most significant bit. Note that the zero-origin convention is used, i.e., the bits are not numbered 1 to 32.

To use these functions, push the number to test ot set on the stack, then push the bit number. Bit numbers below zero will be considered zero; bit numbers over 31 will be considered 31.

.bitset always returns an integer with the specified bit set. (It is similar to .bitor.) .bitclear always returns an integer with the specified bit set. (It is similar to .bitnot followed by .bitand.) .bit? returns zero if the specified bit is clear, otherwise it returns nonzero. (It should not be assumed that this nonzero value is 1.)

The last function, .bitpow2, returns 2^n for n in the range 0 to 31, with 2^31 being -2147483648 since it is a sign bit. This function is used by the single-bit functions and is useful enough in its own right to be made public in the library.

EXAMPLES

    5 (0101) .bitnot (result is -6) (1111...1010)

    5 (0101) 12 (1100) .bitand (result is 4) (0100)

    5 (0101) 12 (1100) .bitor (result is 13) (1101)

    5 (0101) 12 (1100) .bitxor (result is 9) (1001)

    5 -1 (1111...1111) .bitand (result is 5) (-1 is the identity value)

    5 0 (0) .bitor (result is 0) (0 is the identity value)

    5 5 .bitxor (result is 0) (exclusive OR can be used to test equality)

    5 (0101) 0 .bit? (result is nonzero)

    5 (0101) 1 .bit? (result is 0)

    5 (0101) 1 .bitset (result is 7) (0111)

    5 (0101) 2 .bitclear (result is 1) (0001)

    5 .bitpow2 (result is 32) (100000)

BUGS

No attempt is made to ensure that the builtin integer representation is 32-bit two's complement. If the integers -2147483648 through 2147483647 can be represented the behaviour is guaranteed to be correct, even on architectures where the underlying integer representation is not two's complement. 64-bit architectures will behave like 32-bit ones unless certain contants are changed in the code. 16-bit integers will likewise misbehave if the bits 16-31 are ever set (this includes negative numbers.)

AUTHOR

Deborah Pickett (<Ariel> on FDCMuck).