6.3 The MACHINE-WORDS module

6.3.2 Basic and signed single word operations

For all of the following functions, all arguments that are specified as being specialized to <machine-word> accept an instance of <abstract-integer>, which is then coerced to a <machine-word> before performing the operation.

%logior

Function

%logior (#rest machine-words) => (r :: machine-word)

%logxor

Function

%logxor (#rest machine-words) => (r :: machine-word)

%logand

Function

%logand (#rest machine-words) => (r :: machine-word)

%lognot

Function

%lognot (m :: machine-word) => (r :: machine-word)

These four functions have the same semantics as logior, logxor, logand, and lognot in the Dylan library, but they operate on <machine-word>s instead of <integer>s.

%logbit?

Function

%logbit? (index :: integer, m :: machine-word) => (set? :: boolean)

Returns true iff the indexed bit (zero based, counting from the least significant bit) of m is set. An error is signaled unless 0 <= index < $machine-word-size.

%count-low-zeros

Function

%count-low-zeros (m :: machine-word) => (c :: integer)

Returns the number of consecutive zero bits in m counting from the least significant bit.

Note: This is the position of the least significant non-zero bit in m. So if i is the result, then %logbit?(i, m) is true, and for all values of j such that 0 <= j < i, %logbit?(j, m) is false.

%count-high-zeros

Function

%count-high-zeros (m :: machine-word) => (c :: integer)

: Returns the number of consecutive zero bits in m counting from the most significant bit.
: Note: The position of the most significant non-zero bit in m can be computed by subtracting this result from $machine-word-size - 1. So if i is the result and p = ($machine-word-size - i - 1), then %logbit?(p, m) is true, and for all values of j such that p < j < $machine-word-size, %logbit?(j, m) is false.

Function

%+ (m1 :: machine-word, m2 :: machine-word) => (sum :: machine-word, overflow? :: boolean)

: Signed addition.

Function

%- (m1 :: machine-word, m2 :: machine-word) => (difference :: machine-word, overflow? :: boolean)

: Signed subtraction.

Function

%* (m1 :: machine-word, m2 :: machine-word) => (low :: machine-word, high :: machine-word, overflow? :: boolean)

: Signed multiplication. The value of overflow? is false iff the high word result is a sign extension of the low word result.

%floor/

Function

%floor/ (dividend :: machine-word, divisor :: machine-word) => (quotient :: machine-word, remainder :: machine-word)

%ceiling/

Function

%ceiling/ (dividend :: machine-word, divisor :: machine-word) => quotient :: machine-word, remainder :: machine-word

%round/

Function

%round/ (dividend :: machine-word, divisor :: machine-word)=> (quotient :: machine-word, remainder :: machine-word)

%truncate/

Function

%truncate/ (dividend :: machine-word, divisor :: machine-word) => (quotient :: machine-word, remainder :: machine-word)

%divide

Function

%divide (dividend :: machine-word, divisor :: machine-word) => (quotient :: machine-word, remainder :: machine-word)

The functions %divide, %floor/, %ceiling/, %round/, and %truncate/ all perform signed division of the dividend by the divisor, returning a quotient and remainder such that

(quotient * divisor + remainder = dividend)

When the division is inexact (in other words, when the remainder is not zero), the kind of rounding depends on the operation:

%floor/: The quotient is rounded toward negative infinity.
%ceiling/: The quotient is rounded toward positive infinity.
%round/: The quotient is rounded toward the nearest integer. If the mathematical quotient is exactly halfway between two integers, then the resulting quotient is rounded to the nearest even integer.
%truncate/: The quotient is rounded toward zero.
%divide: If both operands are non-negative, then the quotient is rounded toward zero. If either operand is negative, then the direction of rounding is unspecified, as is the sign of the remainder.

For all of these functions, an error is signaled if the value of the divisor is zero or if the correct value for the quotient exceeds the machine word range.

%negative

Function

%negative (m :: machine-word) => (r :: machine-word, overflow? :: boolean)

%abs

Function

%abs (m :: machine-word) => (r :: machine-word, overflow? :: boolean)

%shift-left

Function

%shift-left (m :: machine-word, count :: integer) => (low :: machine-word, high :: machine-word, overflow? :: boolean)

: Arithmetic left shift of m by count. An error is signaled unless 0 <= count < $machine-word-size. The value of overflow? is false iff the high word result is a sign extension of the low word result.

%shift-right

Function

%shift-right (m :: machine-word, count :: integer) => (r :: machine-word)

Arithmetic right shift of m by count. An error is signaled unless 0 <= count < $machine-word-size.