The Revised Maclisp Manual  Page A15  


Bitwise Logical Functions 
BOOLE  Function  (BOOLE key i_{1} i_{2} i_{3} ...) 
Boole is a generalized operator capable of performing any of the 16 bitwise logical operations on its arguments. The first argument, key, is a fixnum which designates the operation desired. The remaining arguments (i_{1}, i_{2}, ...) are the data to be operated on, and must be fixnums. The key is a fourbit number with digits ABCD, where A=1 if f(0,0) is to equal 1, B=1 if f(1,0)=1, C=1 if f(0,1) is to equal 1, and D=1 if f(1,1).
If only i_{1} and i_{2} are given, a single binary operation is performed. If more than 2 of these arguments is given, the selected boolean function is applied first to the first 2 arguments, and then to that result and the third argument, and so on.
The most common values for key are 1 (and), 7 (ior), 6 (xor). However, for stylistic clarity, these operations should be written as LOGAND, LOGIOR, and LOGXOR instead.
Bitwise complement can be done by (BOOLE 6 i_{1} 1.). However, again for style, LOGNOT is preferred.
Examples:
(BOOLE 0. #o1100 #o0101) => 0 ; 0. Constant 0's
(BOOLE 1. #o1100 #o0101) => #o100 ; 1. Logical AND
(BOOLE 2. #o1100 #o0101) => 1
(BOOLE 3. #o1100 #o0101) => #o101
(BOOLE 4. #o1100 #o0101) => #o1000
(BOOLE 5. #o1100 #o0101) => #o1100
(BOOLE 6. #o1100 #o0101) => #o1001 ; 6. Logical XOR
(BOOLE 7. #o1100 #o0101) => #o1101 ; 7. Logical IOR
(BOOLE 8. #o1100 #o0101) => #o1102
(BOOLE 9. #o1100 #o0101) => #o1002
(BOOLE 10. #o1100 #o0101) => #o1101
(BOOLE 11. #o1100 #o0101) => #o1001
(BOOLE 12. #o1100 #o0101) => #o102
(BOOLE 13. #o1100 #o0101) => #o2
(BOOLE 14. #o1100 #o0101) => #o101
(BOOLE 15. #o1100 #o0101) => 1 ; 15. Constant 1's
Common boolean operations 
LOGAND  Function  (LOGAND i_{1} i_{2} ...) 
Returns the logical and of its fixnum arguments. In the compiler, a macro which expands into a call to BOOLE. In the interpreter, a normal function of 2 or more arguments.
LOGIOR  Function  (LOGIOR i_{1} i_{2} ...) 
Returns the logical inclusive or of its fixnum arguments. In the compiler, a macro which expands into a call to BOOLE. In the interpreter, a normal function of 2 or more arguments.
LOGXOR  Function  (LOGXOR i_{1} i_{2} ...) 
Returns the logical exclusive or of its fixnum arguments. In the compiler, a macro which expands into a call to BOOLE. In the interpreter, a normal function of 2 or more arguments.
LOGNOT  Function  (LOGNOT i) 
Returns the logical negation of its fixnum argument. In the compiler, a macro which expands into a call to BOOLE. In the interpreter, a normal function of 1 argument.
Auxiliary Logical Operations 
The functions BITTEST, BITSET, and BITCLEAR described below are not part of the default environment. Users who want to use them should put a form such as this at the top of any file that uses them:
(EVALWHEN (EVAL COMPILE) (IF (NOT (GET 'UMLMAC 'VERSION)) (LOAD '((LISP) UMLMAC))))
BITTEST  Function  (BITTEST bitmask bitvector) 
BITSET  Function  (BITSET bitmask bitvector) 
Returns a fixnum in which all the bits are set if they were set in bitvector or were specified by the fixnum bitmask. Same as (LOGIOR bitmask bitvector).
BITCLEAR  Function  (BITCLEAR bitmask bitvector) 
Returns a fixnum in which all the bits are set if they were set in bitvector unless they were specified by the fixnum bitmask. Same as (BOOLE 2. bitmask bitvector).
Bit Shifting Functions 
LSH  Function  (LSH k i) 
Logical Shift. Returns k shifted left i bits if i is positive, or k shifted right (ABS i) bits if i is negative. 0 bits are shifted in to fill unused positions. The result is undefined if (ABS i) > 36. If i=0, no shift occurs, but the datatype of k is changed to fixnum. (Useful to change a flonum to fixnum for storage in a fixnum array. See FSC)
Note that (LSH 1 1) returns the most positive fixnum for a given implementation.
Examples:
(lsh 4 1) => 8.
(lsh 14 2) => 3.
(lsh 1 1) => 2.
(lsh (fsc 37 #o1000000) 0) => 37.
ASH  Function  (ASH k i) 
ASH is the least intuitive of the arithmetic shift operations. Basically, it is like a LSH except that the high bit (sign bit) is always preserved and sometimes stretches. Specifically: When shifting right (negative 2nd arg), the high (sign) bit is copied into the bits opened by shifting. When shifting left, only the bottom 35 bits are shifted; the sign bit is held constant and zeros pad out opened places on the low end of the word.
For a description of the potential danger of this operation, see Guy Steele's “Arithmetic Shifting Considered Harmful,” MIT AI Memo 378, September 1976.
Examples:
(ASH 3 3) => #o30
(LSH 3 3) => #o30
(ASH 3 3) => #o30
(LSH 3 3) => #o30
(ASH #o1000000 1) => #o400000
(LSH #o1000000 1) => #o377777400000
(ASH #o400000000000 1) => #o400000000000 ;Identity!
(LSH #o400000000000 1) => 0
(ASH #o400000000000 1) => #o200000000000
(LSH #o400000000000 1) => #o200000000000
FSC  Function  (FSC k i) 
This is a hook into the PDP10 floatingpoint scale instruction.
(FSC k #o1000000), where k is a fixnum, will convert it to a floating point number without normalizing it, skipping the actual FSC and just changing the type information of k. (See LSH)
Examples:
(FSC 1.0 1) => 2.0
(FSC 3.0E5 3) => 2400000.0
(FSC 8.0 2) => 2.0
(FSC 3.5 1) => 1.75
(FSC (LSH 4.3 0) #o1000000) => 4.3
ROT  Function  (ROT k i) 
Returns as a fixnum the 36bit representation of k, rotated left i bits if i is positive, or rotated right (ABS i) bits if i is negative. k and i should be fixnums. The results are undefined if (ABS i) > 36.
If k is a flonum, its datatype will be changed to fixnum without affecting its bitpattern. (See LSH and FSC.)
Note that (ROT 1 1) returns the most negative fixnum for a given implementation.
Examples:
(rot 1. 2.) => 4.
(rot 1. 7.) => 1.
(rot 601234. 36.) => 601234.
(rot 1. 2.) => #o200000000000
Bit Extraction Functions 
HAIPART  Function  (HAIPART j i) 
If i is nonnegative, returns the highorder i bits of j; if i is negative, returns the (ABS i) loworder bits of j. j may be a fixnum or bignum; i must be a fixnum. The value returned is a fixnum or a bignum, as appropriate. If (ABS i) is bigger than the number of significant bits in j, (ABS j) is returned.
By the way, HAIPART has been recently identified as buggy such that if j is negative and (HAULONG j) is less than i, it returns a negative number.
Note: HAIPART is pronounced “HIGHpart.”
Examples:
(haipart 7 2) => 3.
(haipart #o1234 3) => 5.
(haipart 153. 4) => 9.
(haipart 123. 4) => 11.
(haipart 123. 4) => 11.
HAULONG  Function  (HAULONG j) 
Returns the number of significant bits in j. j can be a fixnum or a bignum. The result is the least integer not less than the basetwo logarithm of (1+ (ABS j)).
The expression (1+ (HAULONG (LSH 1. 1.))) will return the word size of the machine.
Note: HAULONG is pronounced “HOWlong.”
Examples:
(HAULONG 0) => 0
(HAULONG 3) => 2
(HAULONG 7) => 3
(HAULONG 100000000000000.) => 47.
(HAULONG (LSH 1 1)) => 36. ;on PDP10
Byte Manipulation Functions 
All of the functions on this page are purely functional, in spite of the `imperative' nature of their names. They do not sideeffect their arguments or any location in memory. They simply return a number which satisfies the description of their function.
DEPOSITBYTE  Function  (DEPOSITBYTE word pos size val) 
[PDP10 Only] Returns the fixnum which is the result of placing val in the size bits beginning at bit pos in word. Bits are numbered from right to left, beginning with 0.
Examples:
(DEPOSITBYTE #o12345 3 6 #o43) => #o12435
(DEPOSITBYTE #o12345 3 6 #o03) => #o12035
LOADBYTE  Function  (LOADBYTE word pos size) 
[PDP10 Only] Returns the contents of the size bits beginning at bit pos in word. Bits are numbered from right to left, beginning with 0.
Examples:
(LOADBYTE #o12345 3 6) => #o34
(LOADBYTE #o12345 15. 6) => 0
DPB  Function  (DPB val bytepointer word) 
A LispMcompatible version of the DEPOSITBYTE concept. The second arg, bytepointer, is made from two octal digits specifying the starting position followed by two octal digits specifying the number of bits. The first arg, val, is the value to deposit in word.
Multics users must (%include runtime) to get DPB.
Example:
(DPB #o43 #o0306 #o12345) => #o12435
LDB  Function  (LDB bytepointer word) 
This is a LispMcompatible version of the LOADBYTE concept. The bytepointer is made from two octal digits specifying the starting position followed by two octal digits specifying the number of bits. The second arg is the word from which to extract the specified bitfield.
Multics users must (%include runtime) to get LDB.
Example:
(LDB #o0306 #o12345) => #o34
Byte Manipulation Functions 
*DEPOSITBYTE  Function  (*DEPOSITBYTE word pos size val) 
[PDP10 Only] For use by the compiler only. Same as DEPOSITBYTE.
Example:
(*DEPOSITBYTE #o12345 3 6 #o43) => #o12435
*LOADBYTE  Function  (*LOADBYTE word pos size) 
[PDP10 Only] For use by the compiler only. Same as LOADBYTE.
Example:
(*LOADBYTE #o12345 3 6) => #o34
*DPB  Function  (*DPB val bytepointer word) 
[PDP10 Only] For use by the compiler only. Different from DPB only in that bytepointer is shifted left 24.
Example:
(*DPB #o43 #o0306_24. #o12345) => #o12435
*LDB  Function  (*LDB bytepointer word) 

The Revised Maclisp Manual (Sunday Morning Edition) Published Sunday, December 16, 2007 06:17am EST, and updated Sunday, July 6, 2008. 
