Word structure

June 18, 2026 · View on GitHub

The Word structure provides a type of unsigned integer with modular arithmetic, logical (bit-wise) operations, and conversions. Words are meant to give efficient access to the primitive machine word type of the underlying hardware, and to support bit-level operations on integers.

In Morel, word is a 64-bit unsigned integer (wordSize is 64), LargeWord.word = word, and LargeInt.int = int.

Specified by the Standard ML Basis Library.

Synopsis

type word

val wordSize : int
val toLarge : word -> word
val toLargeX : word -> word
val toLargeWord : word -> word
val toLargeWordX : word -> word
val fromLarge : word -> word
val fromLargeWord : word -> word
val toLargeInt : word -> int
val toLargeIntX : word -> int
val fromLargeInt : int -> word
val toInt : word -> int
val toIntX : word -> int
val fromInt : int -> word
val andb : word * word -> word
val orb : word * word -> word
val xorb : word * word -> word
val notb : word -> word
val << : word * word -> word
val >> : word * word -> word
val ~>> : word * word -> word
val + : word * word -> word
val - : word * word -> word
val * : word * word -> word
val div : word * word -> word
val mod : word * word -> word
val compare : word * word -> order
val < : word * word -> bool
val <= : word * word -> bool
val > : word * word -> bool
val >= : word * word -> bool
val ~ : word -> word
val min : word * word -> word
val max : word * word -> word
val fmt : radix -> word -> string
val toString : word -> string
val fromString : string -> word option

`type word`

is the type of unsigned, fixed-precision integers (words).

`wordSize`

wordSize is the number of bits in type word. In Morel, wordSize is 64. wordSize need not be a power of two; note that word has a fixed, finite precision.

`toLarge`

toLarge w converts w to an equivalent value in LargeWord.word, in the range [0, 2^wordSize - 1]. In Morel, LargeWord.word = word, so this is the identity.

`toLargeX`

toLargeX w is the "sign-extended" conversion of w to LargeWord.word: the wordSize low-order bits of w and toLargeX w are the same, and the remaining bits of toLargeX w are all equal to the most significant bit of w. In Morel, LargeWord.word = word, so this is the identity.

`toLargeWord`

toLargeWord w is a deprecated synonym of toLarge.

`toLargeWordX`

toLargeWordX w is a deprecated synonym of toLargeX.

`fromLarge`

fromLarge w converts w to the value w (mod 2^wordSize) of type word, taking the low-order wordSize bits of the 2's complement representation of w. In Morel, LargeWord.word = word, so this is the identity.

`fromLargeWord`

fromLargeWord w is a deprecated synonym of fromLarge.

`toLargeInt`

toLargeInt w converts w, treated as an integer value in the range [0, 2^wordSize - 1], to LargeInt.int. It raises Overflow if the value cannot be represented as a LargeInt.int. In Morel, LargeInt.int = int, so it raises Overflow when w exceeds Int.maxInt.

`toLargeIntX`

toLargeIntX w converts w, treated as a 2's complement signed integer with wordSize precision, to LargeInt.int. In Morel, LargeInt.int = int (fixed-precision), so it raises Overflow when the value cannot be represented as an int.

`fromLargeInt`

fromLargeInt i converts i of type LargeInt.int to a value of type word, taking the low-order wordSize bits of the 2's complement representation of i.

`toInt`

toInt w converts w, treated as an integer value in the range [0, 2^wordSize - 1], to the default integer type. It raises Overflow if the value cannot be represented as an Int.int.

`toIntX`

toIntX w converts w, treated as a 2's complement signed integer with wordSize precision, to the default integer type. It raises Overflow if the value cannot be represented as an Int.int.

`fromInt`

fromInt i converts i of the default integer type to a value of type word, taking the low-order wordSize bits of the 2's complement representation of i.

`andb`

andb (i, j) (or i.andb j) returns the bit-wise AND of i and j.

`orb`

orb (i, j) (or i.orb j) returns the bit-wise OR of i and j.

`xorb`

xorb (i, j) (or i.xorb j) returns the bit-wise exclusive OR of i and j.

`notb`

notb i (or i.notb ()) returns the bit-wise complement (NOT) of i.

`<<`

i << n shifts i to the left by n bit positions, filling in zeros from the right. It returns (i * 2ⁿ) (mod 2^wordSize). When n >= wordSize the result is 0w0.

`>>`

i >> n shifts i to the right by n bit positions, filling in zeros from the left. It returns floor(i / 2ⁿ). When n >= wordSize the result is 0w0.

`~>>`

i ~>> n shifts i to the right by n bit positions. The value of the leftmost bit of i remains the same; in a 2's complement interpretation this corresponds to sign extension. It returns floor(i / 2ⁿ).

`+`

i + j returns the sum (i + j) (mod 2^wordSize). It does not raise Overflow.

`-`

i - j returns the difference of i and j modulo 2^wordSize: (2^wordSize + i - j) (mod 2^wordSize). It does not raise Overflow.

`*`

i * j returns the product (i * j) (mod 2^wordSize). It does not raise Overflow.

`div`

i div j returns the truncated quotient of i and j, floor(i / j), treating the arguments as unsigned. It raises Div when j = 0w0.

`mod`

i mod j returns the remainder of the division of i by j, i - j * floor(i / j), treating the arguments as unsigned. It raises Div when j = 0w0.

`compare`

compare (i, j) (or i.compare j) returns LESS, EQUAL, or GREATER if and only if i is less than, equal to, or greater than j, respectively, considered as unsigned binary numbers.

`<`

i < j returns true if i is less than j, considered as unsigned.

`<=`

i <= j returns true if i is less than or equal to j, considered as unsigned.

`>`

i > j returns true if i is greater than j, considered as unsigned.

`>=`

i >= j returns true if i is greater than or equal to j, considered as unsigned.

`~`

~ i returns the 2's complement of i.

`min`

min (i, j) (or i.min j) returns the smaller of the arguments, considered as unsigned.

`max`

max (i, j) (or i.max j) returns the larger of the arguments, considered as unsigned.

`fmt`

fmt radix i returns a string containing a representation of i in the given radix. The hexadecimal digits 10 through 15 are represented as #"A" through #"F", respectively. No prefix "0w" or "0wx" is generated.

`toString`

toString i (or i.toString ()) converts a word into a string; equivalent to (fmt StringCvt.HEX i).

`fromString`

fromString s returns SOME (w) if an unsigned hexadecimal number can be parsed from a prefix of string s, ignoring initial whitespace; otherwise it returns NONE. Equivalent to StringCvt.scanString (scan StringCvt.HEX). It raises Overflow when a hexadecimal numeral can be parsed, but is too large to be represented by type word.