The machine-words 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 machine-word and integer are instances of <machine-word> and <integer>, respectively.

The class <machine-word> 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 <machine-word> is 32 bits wide. When running a 64 bit OS, then <machine-word> is 64 bits wide. <machine-word> is disjoint from all other classes specified by the Dylan language.

The == function compares instances of <machine-word> by value.

Useful functions from the Dylan module

This section describes additional methods defined in the dylan module that pertain to <machine-word>. 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 common-dylan library also has these extensions because it uses the dylan library.

odd? Function
Signature:

odd? m => r

Parameters:
Values:
even? Function
Signature:

even? m => r

Parameters:
Values:
zero? Function
Signature:

zero? m => r

Parameters:
Values:

Note

Cannot be used as the name of a result. It is not a valid Dylan name.

positive? Function
Signature:

positive? m => r

Parameters:
Values:
negative? Function
Signature:

negative? m => r

Parameters:
Values:

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 <machine-word>

  • m2 – An instance of <machine-word>

  • i1 – An instance of <abstract-integer>

  • i2 – An instance of <abstract-integer>

Values:
Discussion:

The comparison is performed with the <machine-word> arguments interpreted as signed integer values.

< Function
Signature:

< m1 m2 => r

Signature:

< i1 m2 => r

Signature:

< m1 i2 => r

Parameters:

  • m1 – An instance of <machine-word>

  • m2 – An instance of <machine-word>

  • i1 – An instance of <abstract-integer>

  • i2 – An instance of <abstract-integer>

Values:
Discussion:

The comparison is performed with the <machine-word> arguments interpreted as signed integer values.

as Function
Signature:

as t == <integer> m => r

Parameters:
Values:
Discussion:

The result is an <integer> with the same value as m when interpreted as a signed integer value. An error is signaled if the value of m cannot be represented as an instance of <integer>.

as Function
Signature:

as t == <abstract-integer> m => r

Parameters:
Values:

  • r – An instance of <abstract-integer>

Discussion:

The result is an <abstract-integer> with the same value as m when interpreted as a signed integer value.

(The uses for an instance of <abstract-integer> that is not also an instance of <integer> are rather limited without the Generic-Arithmetic library.)

as Function
Signature:

as t == <machine-word> i => r

Parameters:

  • i – An instance of <abstract-integer>

Values:
Discussion:

If the value of i is outside the machine word range, then the result consists of the low $machine-word-size bits of the twos-complement representation of i. If any of the discarded bits differ from the sign of i, then an error is signaled.

limited Function
Signature:

limited t == <machine-word> #key signed? min max => r

Parameters:
Values:

  • r – An instance of <type>

Discussion:

If the signed? argument is true (the default) then the min and max arguments are interpreted as signed values. When signed? is false, the min and max arguments are interpreted as unsigned values. The default value for each of min and max depends on the value of signed?. The defaults are taken from the corresponding minimum and maximum machine word values (see $maximum-signed-machine-word and related constants below).

For convenience, the values of min and/or max may also be instances of <abstract-integer>, in which case they are coerced to instances of <machine-word> as if by using as.

The machine-words Module

This section contains a reference entry for each item exported from the machine-words module, which is exported by the common-dylan library.

<machine-word> 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:

<object>

Discussion:

The class <machine-word> represents a limited range of integral values. The representation used has the natural size suggested by the implementation architecture. The class <machine-word> is disjoint from all other classes specified by the Dylan language.

Operations:

The <machine-word> class provides the operations described below and in Useful functions from the Dylan module.

Variables

The following variables are exported from the machine-words module.

$machine-word-size Constant
Type:

<integer>

Discussion:

The number of bits in the representation of a <machine-word>.

$maximum-signed-machine-word Constant
Type:

<machine-word>

Discussion:

The largest machine word, when interpreted as a signed integer value.

$minimum-signed-machine-word Constant
Type:

<machine-word>

Discussion:

The smallest machine word, when interpreted as a signed integer value.

$maximum-unsigned-machine-word Constant
Type:

<machine-word>

Discussion:

The largest machine word, when interpreted as an unsigned integer value.

$minimum-unsigned-machine-word Constant
Type:

<machine-word>

Discussion:

The smallest machine word, when interpreted as an unsigned integer value.

as-unsigned Function
Signature:

as-unsigned t m => result

Parameters:
Values:

  • result – An instance of t

Discussion:

The value of m is interpreted as an unsigned value and converted to an instance of <abstract-integer>, then the result of that conversion is converted to type t using as.

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
Signature:

%logior #rest machine-words => r

Parameters:
Values:
%logxor Function
Signature:

%logxor #rest machine-words => r

Parameters:
Values:
%logand Function
Signature:

%logand #rest machine-words => r

Parameters:
Values:
%lognot Function
Signature:

%lognot m => r

Parameters:
Values:

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

%logbit? Function
Signature:

%logbit? index m => set?

Parameters:
Values:
Discussion:

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
Signature:

%count-low-zeros m => c

Parameters:
Values:
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 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
Signature:

%count-high-zeros m => c

Parameters:
Discussion:

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.

%count-ones Function
Signature:

%count-ones m => c

Parameters:

  • m – An instance of <machine-word>.

  • 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:
Values:
Discussion:

Signed addition.

%- Function
Signature:

%- m1 m2 => difference overflow?

Parameters:
Values:
Discussion:

Signed subtraction.

%\* Function
Signature:

%* m1 m2 => low high overflow?

Parameters:
Values:
Discussion:

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

%floor/ Function
Signature:

%floor/ dividend divisor => quotient remainder

Parameters:
Values:
%ceiling/ Function
Signature:

%ceiling/ dividend divisor => quotient remainder

Parameters:
Values:
%round/ Function
Signature:

%round/ dividend divisor => quotient remainder

Parameters:
Values:
%truncate/ Function
Signature:

%truncate/ dividend divisor => quotient remainder

Parameters:
Values:
%divide Function
Signature:

%divide/ dividend divisor => quotient remainder

Parameters:
Values:

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
Signature:

%negative m => r overflow?

Parameters:
Values:
%abs Function
Signature:

%abs m => r overflow?

Parameters:
Values:
%shift-left Function
Signature:

%shift-left m count => low high overflow?

Parameters:
Values:
Discussion:

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
Signature:

%shift-right m count => r

Parameters:
Values:
Discussion:

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

Overflow signaling 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.

so%+ Function
Signature:

so%+ m1 m2 => sum

Parameters:
Values:
Discussion:

Signed addition. An error is signaled on overflow.

so%- Function
Signature:

so%- m1 m2 => difference

Parameters:
Values:
Discussion:

Signed subtraction. An error is signaled on overflow.

so%\* Function
Signature:

so%* m1 m2 => product

Parameters:
Values:
Discussion:

Signed multiplication. An error is signaled on overflow.

so%negative Function
Signature:

so%negative m => r

Parameters:
Values:
Discussion:

Negation. An error is signaled on overflow.

so%abs Function
Signature:

so%abs m => r

Parameters:
Values:
Discussion:

Absolute value. An error is signaled on overflow.

so%shift-left Function
Signature:

so%shift-left m count => r

Parameters:
Values:
Discussion:

Arithmetic left shift of m by count. An error is signaled unless 0 <= count < $machine-word-size. 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 <machine-word> accept an instance of <abstract-integer>, which is then coerced to a <machine-word> before performing the operation.

d%floor/ Function
Signature:

d%floor/ dividend-low dividend-high divisor => quotient remainder

Parameters:
Values:
d%ceiling/ Function
Signature:

d%ceiling/ dividend-low dividend-high divisor => quotient remainder

Parameters:
Values:
d%round/ Function
Signature:

d%round/ dividend-low dividend-high divisor => quotient remainder

Parameters:
Values:
d%truncate/ Function
Signature:

d%truncate/ dividend-low dividend-high divisor => quotient remainder

Parameters:
Values:
d%divide Function
Signature:

d%divide dividend-low dividend-high divisor => quotient remainder

Parameters:
Values:

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 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.

Unsigned 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.

u%+ Function
Signature:

u%+ m1 m2 => sum carry

Parameters:
Values:
Discussion:

Unsigned addition. The value represented by carry is either 0 or 1.

u%- Function
Signature:

u%- m1 m2 => sum borrow

Parameters:
Values:
Discussion:

Unsigned subtraction. The value represented by borrow is either 0 or 1.

u%\* Function
Signature:

u%* m1 m2 => low high

Parameters:
Values:
Discussion:

Unsigned multiplication.

u%divide Function
Signature:

u%divide dividend divisor => quotient remainder

Parameters:
Values:
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%rotate-left Function
Signature:

u%rotate-left m count => r

Parameters:
Values:
Discussion:

Logical left rotation of m by count. An error is signaled unless 0 <= count < $machine-word-size.

u%rotate-right Function
Signature:

u%rotate-right m count => r

Parameters:
Values:
Discussion:

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

u%shift-left Function
Signature:

u%shift-left m count => r

Parameters:
Values:
Discussion:

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

u%shift-right Function
Signature:

u%shift-right m count => r

Parameters:
Values:
Discussion:

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

u%< Function
Signature:

u%< m1 m2 => smaller?

Parameters:
Values:
Discussion:

Unsigned comparison.

Unsigned double 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.

ud%divide Function
Signature:

ud%divide dividend-low dividend-high divisor => quotient remainder

Parameters:
Values:
Discussion:

Performs unsigned division of the double word 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 or if the correct value for the quotient exceeds the machine word range.

ud%shift-left Function
Signature:

ud%shift-left low high count => low high

Parameters:
Values:
Discussion:

Logical left shift by count of the double word value represented by low and high. An error is signaled unless 0 <= count < $machine-word-size.

ud%shift-right Function
Signature:

ud%shift-right low high count => low high

Parameters:
Values:
Discussion:

Logical right shift by count of the double word value represented by low and high. An error is signaled unless 0 <= count < $machine-word-size.