Skip to content

word.md

Latest commit

 

History

History
322 lines (235 loc) · 11.4 KB

word.md

File metadata and controls

322 lines (235 loc) · 11.4 KB
Raw

Word structure

Up to index

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 scan : radix -> (char, 'a) reader -> (word, 'a) reader
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, 2wordSize - 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 2wordSize) 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, 2wordSize - 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, 2wordSize - 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 * 2n) (mod 2wordSize). 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 / 2n). 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 / 2n).

+

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

-

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

*

i * j returns the product (i * j) (mod 2wordSize). 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).

scan

scan radix getc strm returns SOME (w, rest) if an unsigned number in the format denoted by radix can be parsed from a prefix of the character stream strm using the character input function getc, where w is the value parsed and rest is the remainder of the character stream. NONE is returned otherwise. This function raises Overflow when a number can be parsed, but is too large to fit in type word.

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.