The machinewords Module¶
This document describes a number of extensions to the Dylan language which are
available from the dylan
library.
Throughout this document, arguments are instances of the class specified
by the argument name, unless otherwise noted. Thus, the arguments
machineword and integer are instances of <machineword>
and
<integer>
, respectively.
The class <machineword>
is a sealed subclass of <object>
,
defined in the dylan
library, representing a limited range of integral
values. The representation used has the natural size suggested by the
implementation architecture. When running a 32 bit OS, a
<machineword>
is 32 bits wide. When running a 64 bit OS, then
<machineword>
is 64 bits wide. <machineword>
is disjoint
from all other classes specified by the Dylan language.
The ==
function compares instances of <machineword>
by value.
Useful functions from the Dylan module¶
This section describes additional methods defined in the dylan
module that
pertain to <machineword>
. Note that this section only describes
extensions to the dylan
library; for complete descriptions, you should also
refer to the Dylan Reference Manual.
Note that the commondylan
library also has these extensions because it
uses the dylan
library.

odd?
Function¶  Signature
odd? m => r
 Parameters
m – An instance of
<machineword>
 Values
r – An instance of
<boolean>

even?
Function¶  Signature
even? m => r
 Parameters
m – An instance of
<machineword>
 Values
r – An instance of
<boolean>

zero?
Function¶  Signature
zero? m => r
 Parameters
m – An instance of
<machineword>
 Values
r – An instance of
<boolean>
Note
Cannot be used as the name of a result. It is not a valid Dylan name.

positive?
Function¶  Signature
positive? m => r
 Parameters
m – An instance of
<machineword>
 Values
r – An instance of
<boolean>

negative?
Function¶  Signature
negative? m => r
 Parameters
m – An instance of
<machineword>
 Values
r – An instance of
<boolean>
These functions return a result based on interpreting m
as a signed
integer value.

\=
Function¶  Signature
= m1 m2 => r
 Signature
= i1 m2 => r
 Signature
= m1 i2 => r
 Parameters
m1 – An instance of
<machineword>
m2 – An instance of
<machineword>
i1 – An instance of
<abstractinteger>
i2 – An instance of
<abstractinteger>
 Values
r – An instance of
<boolean>
 Discussion
The comparison is performed with the
<machineword>
arguments interpreted as signed integer values.

<
Function¶  Signature
< m1 m2 => r
 Signature
< i1 m2 => r
 Signature
< m1 i2 => r
 Parameters
m1 – An instance of
<machineword>
m2 – An instance of
<machineword>
i1 – An instance of
<abstractinteger>
i2 – An instance of
<abstractinteger>
 Values
r – An instance of
<boolean>
 Discussion
The comparison is performed with the
<machineword>
arguments interpreted as signed integer values.

as
Function¶  Signature
as t == <integer> m => r
 Parameters
m – An instance of
<machineword>
 Values
r – An instance of
<integer>
 Discussion
The result is an
<integer>
with the same value asm
when interpreted as a signed integer value. An error is signaled if the value ofm
cannot be represented as an instance of<integer>
.

as
Function  Signature
as t == <abstractinteger> m => r
 Parameters
m – An instance of
<machineword>
 Values
r – An instance of
<abstractinteger>
 Discussion
The result is an
<abstractinteger>
with the same value asm
when interpreted as a signed integer value.(The uses for an instance of
<abstractinteger>
that is not also an instance of<integer>
are rather limited without the GenericArithmetic library.)

as
Function  Signature
as t == <machineword> i => r
 Parameters
i – An instance of
<abstractinteger>
 Values
r – An instance of
<machineword>
 Discussion
If the value of
i
is outside the machine word range, then the result consists of the low$machinewordsize
bits of the twoscomplement representation ofi
. If any of the discarded bits differ from the sign ofi
, then an error is signaled.

limited
Function¶  Signature
limited t == <machineword> #key signed? min max => r
 Parameters
signed? (#key) – An instance of
<boolean>
. Defaults to#t
min (#key) – An instance of
<machineword>
max (#key) – An instance of
<machineword>
 Values
r – An instance of
<type>
 Discussion
If the
signed?
argument is true (the default) then themin
andmax
arguments are interpreted as signed values. Whensigned?
is false, themin
andmax
arguments are interpreted as unsigned values. The default value for each of min and max depends on the value ofsigned?
. The defaults are taken from the corresponding minimum and maximum machine word values (see$maximumsignedmachineword
and related constants below).For convenience, the values of
min
and/ormax
may also be instances of<abstractinteger>
, in which case they are coerced to instances of<machineword>
as if by usingas
.
The machinewords Module¶
This section contains a reference entry for each item exported from the
machinewords
module, which is exported by the commondylan
library.

<machineword>
Sealed Class¶  Summary
The class of objects that can represent a limited range of integral values that are a natural fit for the current machine architecture.
 Superclasses
 Discussion
The class
<machineword>
represents a limited range of integral values. The representation used has the natural size suggested by the implementation architecture. The class<machineword>
is disjoint from all other classes specified by the Dylan language. Operations
The
<machineword>
class provides the operations described below and in Useful functions from the Dylan module.
Variables¶
The following variables are exported from the machinewords
module.

$machinewordsize
Constant¶  Type
 Discussion
The number of bits in the representation of a
<machineword>
.

$maximumsignedmachineword
Constant¶  Type
 Discussion
The largest machine word, when interpreted as a signed integer value.

$minimumsignedmachineword
Constant¶  Type
 Discussion
The smallest machine word, when interpreted as a signed integer value.

$maximumunsignedmachineword
Constant¶  Type
 Discussion
The largest machine word, when interpreted as an unsigned integer value.

$minimumunsignedmachineword
Constant¶  Type
 Discussion
The smallest machine word, when interpreted as an unsigned integer value.

asunsigned
Function¶  Signature
asunsigned t m => result
 Parameters
t – A type
m – An instance of
<machineword>
 Values
result – An istance of
t
 Discussion
The value of
m
is interpreted as an unsigned value and converted to an instance of<abstractinteger>
, then the result of that conversion is converted to typet
usingas
.
Basic and signed single word operations¶
For all of the following functions, all arguments that are specified as being
specialized to <machineword>
accept an instance of
<abstractinteger>
, which is then coerced to a <machineword>
before performing the operation.

%logior
Function¶  Signature
%logior #rest machinewords => r
 Parameters
machinewords (#rest) – An instance of
<machineword>
 Values
r – An instance of
<machineword>

%logxor
Function¶  Signature
%logxor #rest machinewords => r
 Parameters
machinewords (#rest) – An instance of
<machineword>
 Values
r – An instance of
<machineword>

%logand
Function¶  Signature
%logand #rest machinewords => r
 Parameters
machinewords (#rest) – An instance of
<machineword>
 Values
r – An instance of
<machineword>

%lognot
Function¶  Signature
%lognot m => r
 Parameters
m – An instance of
<machineword>
 Values
r – An instance of
<machineword>
These four functions have the same semantics as logior
, logxor
,
logand
, and lognot
in the dylan
library, but they operate on
<machineword>
instead of <integer>
.

%logbit?
Function¶  Signature
%logbit? index m => set?
 Parameters
index – An instance of
<integer>
m – An instance of
<machineword>
 Values
set? – An instance of
<boolean>
 Discussion
Returns true iff the indexed bit (zero based, counting from the least significant bit) of
m
is set. An error is signaled unless0 <= index < $machinewordsize
.

%countlowzeros
Function¶  Signature
%countlowzeros m => c
 Parameters
m – An instance of
<machineword>
 Values
c – An instance of
<integer>
 Discussion
Returns the number of consecutive zero bits in
m
counting from the least significant bit.
Note
This is the position of the least significant nonzero 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.

%counthighzeros
Function¶  Signature
%counthighzeros m => c
 Parameters
m – An instance of
<machineword>
c – An instance of
<integer>
 Discussion
Returns the number of consecutive zero bits in
m
counting from the most significant bit.
Note
The position of the most significant nonzero bit in m
can be
computed by subtracting this result from $machinewordsize  1
. So
if i
is the result and p = ($machinewordsize  i  1)
, then
%logbit?(p, m)
is true, and for all values of j
such that p < j <
$machinewordsize*, *%logbit?(j, m)
is false.

%countones
Function¶  Signature
%countones m => c
 Parameters
m – An instance of
<machineword>
.c – An instance of
<integer>
.
 Discussion
Returns the number of bits in m which have been set to 1.

%+
Function¶  Signature
%+ m1 m2 => sum overflow?
 Parameters
m1 – An instance of
<machineword>
m2 – An instance of
<machineword>
 Values
sum – An instance of
<machineword>
overflow? – An instance of
<boolean>
 Discussion
Signed addition.

%
Function¶  Signature
% m1 m2 => difference overflow?
 Parameters
m1 – An instance of
<machineword>
m2 – An instance of
<machineword>
 Values
difference – An instance of
<machineword>
overflow? – An instance of
<boolean>
 Discussion
Signed subtraction.

%\*
Function¶  Signature
%* m1 m2 => low high overflow?
 Parameters
m1 – An instance of
<machineword>
m2 – An instance of
<machineword>
 Values
low – An instance of
<machineword>
high – An instance of
<machineword>
overflow? – An instance of
<boolean>
 Discussion
Signed multiplication. The value of
overflow?
is false iff thehigh
word result is a sign extension of thelow
word result.

%floor/
Function¶  Signature
%floor/ dividend divisor => quotient remainder
 Parameters
dividend – An instance of
<machineword>
divisor – An instance of
<machineword>
 Values
quotient – An instance of
<machineword>
remainder – An instance of
<machineword>

%ceiling/
Function¶  Signature
%ceiling/ dividend divisor => quotient remainder
 Parameters
dividend – An instance of
<machineword>
divisor – An instance of
<machineword>
 Values
quotient – An instance of
<machineword>
remainder – An instance of
<machineword>

%round/
Function¶  Signature
%round/ dividend divisor => quotient remainder
 Parameters
dividend – An instance of
<machineword>
divisor – An instance of
<machineword>
 Values
quotient – An instance of
<machineword>
remainder – An instance of
<machineword>

%truncate/
Function¶  Signature
%truncate/ dividend divisor => quotient remainder
 Parameters
dividend – An instance of
<machineword>
divisor – An instance of
<machineword>
 Values
quotient – An instance of
<machineword>
remainder – An instance of
<machineword>

%divide
Function¶  Signature
%divide/ dividend divisor => quotient remainder
 Parameters
dividend – An instance of
<machineword>
divisor – An instance of
<machineword>
 Values
quotient – An instance of
<machineword>
remainder – An instance of
<machineword>
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 nonnegative, 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¶  Signature
%negative m => r overflow?
 Parameters
m – An instance of
<machineword>
 Values
r – An instance of
<machineword>
overflow? – An instance of
<boolean>

%abs
Function¶  Signature
%abs m => r overflow?
 Parameters
m – An instance of
<machineword>
 Values
r – An instance of
<machineword>
overflow? – An instance of
<boolean>

%shiftleft
Function¶  Signature
%shiftleft m count => low high overflow?
 Parameters
m – An instance of
<machineword>
count – An instance of
<integer>
 Values
low – An instance of
<machineword>
high – An instance of
<machineword>
overflow? – An instance of
<boolean>
 Discussion
Arithmetic left shift of
m
by count. An error is signaled unless0 <= count < $machinewordsize
. The value ofoverflow?
is false iff the high word result is a sign extension of the low word result.

%shiftright
Function¶  Signature
%shiftright m count => r
 Parameters
m – An instance of
<machineword>
count – An instance of
<integer>
 Values
r – An instance of
<machineword>
 Discussion
Arithmetic right shift of
m
bycount
. An error is signaled unless0 <= count < $machinewordsize
.
Overflow signaling operations¶
For all of the following functions, all arguments that are specified as being
specialized to <machineword>
accept an instance of
<abstractinteger>
, which is then coerced to a <machineword>
before performing the operation.

so%+
Function¶  Signature
so%+ m1 m2 => sum
 Parameters
m1 – An instance of
<machineword>
m2 – An instance of
<machineword>
 Values
sum – An instance of
<machineword>
 Discussion
Signed addition. An error is signaled on overflow.

so%
Function¶  Signature
so% m1 m2 => difference
 Parameters
m1 – An instance of
<machineword>
m2 – An instance of
<machineword>
 Values
difference – An instance of
<machineword>
 Discussion
Signed subtraction. An error is signaled on overflow.

so%\*
Function¶  Signature
so%* m1 m2 => product
 Parameters
m1 – An instance of
<machineword>
m2 – An instance of
<machineword>
 Values
product – An instance of
<machineword>
 Discussion
Signed multiplication. An error is signaled on overflow.

so%negative
Function¶  Signature
so%negative m => r
 Parameters
m – An instance of
<machineword>
 Values
r – An instance of
<machineword>
 Discussion
Negation. An error is signaled on overflow.

so%abs
Function¶  Signature
so%abs m => r
 Parameters
m – An instance of
<machineword>
 Values
r – An instance of
<machineword>
 Discussion
Absolute value. An error is signaled on overflow.

so%shiftleft
Function¶  Signature
so%shiftleft m count => r
 Parameters
m – An instance of
<machineword>
count – An instance of
<integer>
 Values
r – An instance of
<machineword>
 Discussion
Arithmetic left shift of
m
bycount
. An error is signaled unless0 <= count < $machinewordsize
. An error is signaled on overflow.
Signed double word operations¶
For all of the following functions, all arguments that are specified as being
specialized to <machineword>
accept an instance of
<abstractinteger>
, which is then coerced to a <machineword>
before performing the operation.

d%floor/
Function¶  Signature
d%floor/ dividendlow dividendhigh divisor => quotient remainder
 Parameters
dividendlow – An instance of
<machineword>
dividendhigh – An instance of
<machineword>
divisor – An instance of
<machineword>
 Values
quotient – An instance of
<machineword>
remainder – An instance of
<machineword>

d%ceiling/
Function¶  Signature
d%ceiling/ dividendlow dividendhigh divisor => quotient remainder
 Parameters
dividendlow – An instance of
<machineword>
dividendhigh – An instance of
<machineword>
divisor – An instance of
<machineword>
 Values
quotient – An instance of
<machineword>
remainder – An instance of
<machineword>

d%round/
Function¶  Signature
d%round/ dividendlow dividendhigh divisor => quotient remainder
 Parameters
dividendlow – An instance of
<machineword>
dividendhigh – An instance of
<machineword>
divisor – An instance of
<machineword>
 Values
quotient – An instance of
<machineword>
remainder – An instance of
<machineword>

d%truncate/
Function¶  Signature
d%truncate/ dividendlow dividendhigh divisor => quotient remainder
 Parameters
dividendlow – An instance of
<machineword>
dividendhigh – An instance of
<machineword>
divisor – An instance of
<machineword>
 Values
quotient – An instance of
<machineword>
remainder – An instance of
<machineword>

d%divide
Function¶  Signature
d%divide dividendlow dividendhigh divisor => quotient remainder
 Parameters
dividendlow – An instance of
<machineword>
dividendhigh – An instance of
<machineword>
divisor – An instance of
<machineword>
 Values
quotient – An instance of
<machineword>
remainder – An instance of
<machineword>
The functions d%divide
, d%floor/
, d%ceiling/
,
d%round/
, and d%truncate/
all perform signed division of the
double word 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:
d%floor/
The quotient is rounded toward negative infinity.d%ceiling/
The quotient is rounded toward positive infinity.d%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.d%truncate/
The quotient is rounded toward zero.d%divide
If both operands are nonnegative, 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.
Unsigned single word operations¶
For all of the following functions, all arguments that are specified as being
specialized to <machineword>
accept an instance of
<abstractinteger>
, which is then coerced to a <machineword>
before performing the operation.

u%+
Function¶  Signature
u%+ m1 m2 => sum carry
 Parameters
m1 – An instance of
<machineword>
m2 – An instance of
<machineword>
 Values
sum – An instance of
<machineword>
carry – An instance of
<machineword>
 Discussion
Unsigned addition. The value represented by
carry
is either 0 or 1.

u%
Function¶  Signature
u% m1 m2 => sum borrow
 Parameters
m1 – An instance of
<machineword>
m2 – An instance of
<machineword>
 Values
sum – An instance of
<machineword>
borrow – An instance of
<machineword>
 Discussion
Unsigned subtraction. The value represented by
borrow
is either 0 or 1.

u%\*
Function¶  Signature
u%* m1 m2 => low high
 Parameters
m1 – An instance of
<machineword>
m2 – An instance of
<machineword>
 Values
low – An instance of
<machineword>
high – An instance of
<machineword>
 Discussion
Unsigned multiplication.

u%divide
Function¶  Signature
u%divide dividend divisor => quotient remainder
 Parameters
dividend – An instance of
<machineword>
divisor – An instance of
<machineword>
 Values
quotient – An instance of
<machineword>
remainder – An instance of
<machineword>
 Discussion
Performs unsigned division of the dividend by the divisor, returning a quotient and remainder such that
quotient * divisor + remainder = dividend
An error is signaled if the value of the
divisor
is zero.

u%rotateleft
Function¶  Signature
u%rotateleft m count => r
 Parameters
m – An instance of
<machineword>
count – An instance of
<integer>
 Values
r – An instance of
<machineword>
 Discussion
Logical left rotation of
m
bycount
. An error is signaled unless0 <= count < $machinewordsize
.

u%rotateright
Function¶  Signature
u%rotateright m count => r
 Parameters
m – An instance of
<machineword>
count – An instance of
<integer>
 Values
r – An instance of
<machineword>
 Discussion
Logical right rotation of
m
bycount
. An error is signaled unless0 <= count < $machinewordsize
.

u%shiftleft
Function¶  Signature
u%shiftleft m count => r
 Parameters
m – An instance of
<machineword>
count – An instance of
<integer>
 Values
r – An instance of
<machineword>
 Discussion
Logical left shift of
m
bycount
. An error is signaled unless0 <= count < $machinewordsize
.

u%shiftright
Function¶  Signature
u%shiftright m count => r
 Parameters
m – An instance of
<machineword>
count – An instance of
<integer>
 Values
r – An instance of
<machineword>
 Discussion
Logical right shift of
m
bycount
. An error is signaled unless0 <= count < $machinewordsize
.

u%<
Function¶  Signature
u%< m1 m2 => smaller?
 Parameters
m1 – An instance of
<machineword>
m2 – An instance of
<machineword>
 Values
smaller? – An instance of
<boolean>
 Discussion
Unsigned comparison.
Unsigned double word operations¶
For all of the following functions, all arguments that are specified as being
specialized to <machineword>
accept an instance of
<abstractinteger>
, which is then coerced to a <machineword>
before performing the operation.

ud%divide
Function¶  Signature
ud%divide dividendlow dividendhigh divisor => quotient remainder
 Parameters
dividendlow – An instance of
<machineword>
dividendhigh – An instance of
<machineword>
divisor – An instance of
<machineword>
 Values
quotient – An instance of
<machineword>
remainder – An instance of
<machineword>
 Discussion
Performs unsigned division of the double word dividend by the
divisor
, returning aquotient
andremainder
such that(quotient * divisor + remainder = dividend)
An error is signaled if the value of the
divisor
is zero or if the correct value for thequotient
exceeds the machine word range.

ud%shiftleft
Function¶  Signature
ud%shiftleft low high count => low high
 Parameters
low – An instance of
<machineword>
high – An instance of
<machineword>
count – An instance of
<integer>
 Values
low – An instance of
<machineword>
high – An instance of
<machineword>
 Discussion
Logical left shift by
count
of the double word value represented bylow
andhigh
. An error is signaled unless0 <= count < $machinewordsize
.

ud%shiftright
Function¶  Signature
ud%shiftright low high count => low high
 Parameters
low – An instance of
<machineword>
high – An instance of
<machineword>
count – An instance of
<integer>
 Values
low – An instance of
<machineword>
high – An instance of
<machineword>
 Discussion
Logical right shift by
count
of the double word value represented bylow
andhigh
. An error is signaled unless0 <= count < $machinewordsize
.