BasisLibrary

MLton

The Standard ML Basis Library is a collection of modules dealing with basic types, input/output, OS interfaces, and simple datatypes. It is intended as a portable library usable across all implementations of SML. For the official online version of the Basis Library specification, see https://smlfamily.github.io/Basis. The Standard ML Basis Library is a book version that includes all of the online version and more. For a reverse chronological list of changes to the specification, see https://smlfamily.github.io/Basis/history.html.

MLton implements all of the required portions of the Basis Library. MLton also implements many of the optional structures. In the future, MLton will also implement proposed improvements to the Basis Library.

You can obtain a complete and current list of what’s available using mlton -show-basis (see ShowBasis). By default, MLton makes the Basis Library available to user programs. You can also access the Basis Library from ML Basis files.

MLton purposefully hides the representation of unspecified Basis Library types with opaque signature matching. That is, unless the Basis Library specifies that a structure’s type is equal to some other type, the type will be opaque and will not be seen as equal to any type but itself.

Below is a complete list of what MLton implements.

Top-level types and constructors

eqtype 'a array

datatype bool = false | true

eqtype char

type exn

eqtype int

datatype 'a list = nil | :: of ('a * 'a list)

datatype 'a option = NONE | SOME of 'a

datatype order = EQUAL | GREATER | LESS

type real

datatype 'a ref = ref of 'a

eqtype string

type substring

eqtype unit

eqtype 'a vector

eqtype word

Top-level exception constructors

Bind

Chr

Div

Domain

Empty

Fail of string

Match

Option

Overflow

Size

Span

Subscript

Top-level values

MLton does not implement the optional top-level value use: string -> unit, which conflicts with whole-program compilation because it allows new code to be loaded dynamically.

MLton implements all other top-level values:

!, :=, <>, =, @, ^, app, before, ceil, chr, concat, exnMessage, exnName, explode, floor, foldl, foldr, getOpt, hd, ignore, implode, isSome, length, map, not, null, o, ord, print, real, rev, round, size, str, substring, tl, trunc, valOf, vector

Overloaded identifiers

*, +, -, /, <, ⇐, >, >=, ~, abs, div, mod

Top-level signatures

ARRAY

ARRAY2

ARRAY_SLICE

BIN_IO

BIT_FLAGS

BOOL

BYTE

CHAR

COMMAND_LINE

DATE

GENERAL

GENERIC_SOCK

IEEE_REAL

IMPERATIVE_IO

INET_SOCK

INTEGER

INT_INF

IO

LIST

LIST_PAIR

MATH

MONO_ARRAY

MONO_ARRAY2

MONO_ARRAY_SLICE

MONO_VECTOR

MONO_VECTOR_SLICE

NET_HOST_DB

NET_PROT_DB

NET_SERV_DB

OPTION

OS

OS_FILE_SYS

OS_IO

OS_PATH

OS_PROCESS

PACK_REAL

PACK_WORD

POSIX

POSIX_ERROR

POSIX_FILE_SYS

POSIX_IO

POSIX_PROCESS

POSIX_PROC_ENV

POSIX_SIGNAL

POSIX_SYS_DB

POSIX_TTY

PRIM_IO

REAL

SOCKET

STREAM_IO

STRING

STRING_CVT

SUBSTRING

TEXT

TEXT_IO

TEXT_STREAM_IO

TIME

TIMER

UNIX

UNIX_SOCK

VECTOR

VECTOR_SLICE

WORD

Top-level structures

structure Array: ARRAY

structure Array2: ARRAY2

structure ArraySlice: ARRAY_SLICE

structure BinIO: BIN_IO

structure BinPrimIO: PRIM_IO

structure Bool: BOOL

structure BoolArray: MONO_ARRAY

structure BoolArray2: MONO_ARRAY2

structure BoolArraySlice: MONO_ARRAY_SLICE

structure BoolVector: MONO_VECTOR

structure BoolVectorSlice: MONO_VECTOR_SLICE

structure Byte: BYTE

structure Char: CHAR

Char characters correspond to ISO-8859-1. The Char functions do not depend on locale.

structure CharArray: MONO_ARRAY

structure CharArray2: MONO_ARRAY2

structure CharArraySlice: MONO_ARRAY_SLICE

structure CharVector: MONO_VECTOR

structure CharVectorSlice: MONO_VECTOR_SLICE

structure CommandLine: COMMAND_LINE

structure Date: DATE

Date.fromString and Date.scan accept a space in addition to a zero for the first character of the day of the month. The Basis Library specification only allows a zero.

structure FixedInt: INTEGER

structure General: GENERAL

structure GenericSock: GENERIC_SOCK

structure IEEEReal: IEEE_REAL

structure INetSock: INET_SOCK

structure IO: IO

structure Int: INTEGER

structure Int1: INTEGER

structure Int2: INTEGER

structure Int3: INTEGER

structure Int4: INTEGER

…

structure Int31: INTEGER

structure Int32: INTEGER

structure Int64: INTEGER

structure IntArray: MONO_ARRAY

structure IntArray2: MONO_ARRAY2

structure IntArraySlice: MONO_ARRAY_SLICE

structure IntVector: MONO_VECTOR

structure IntVectorSlice: MONO_VECTOR_SLICE

structure Int8: INTEGER

structure Int8Array: MONO_ARRAY

structure Int8Array2: MONO_ARRAY2

structure Int8ArraySlice: MONO_ARRAY_SLICE

structure Int8Vector: MONO_VECTOR

structure Int8VectorSlice: MONO_VECTOR_SLICE

structure Int16: INTEGER

structure Int16Array: MONO_ARRAY

structure Int16Array2: MONO_ARRAY2

structure Int16ArraySlice: MONO_ARRAY_SLICE

structure Int16Vector: MONO_VECTOR

structure Int16VectorSlice: MONO_VECTOR_SLICE

structure Int32: INTEGER

structure Int32Array: MONO_ARRAY

structure Int32Array2: MONO_ARRAY2

structure Int32ArraySlice: MONO_ARRAY_SLICE

structure Int32Vector: MONO_VECTOR

structure Int32VectorSlice: MONO_VECTOR_SLICE

structure Int64Array: MONO_ARRAY

structure Int64Array2: MONO_ARRAY2

structure Int64ArraySlice: MONO_ARRAY_SLICE

structure Int64Vector: MONO_VECTOR

structure Int64VectorSlice: MONO_VECTOR_SLICE

structure IntInf: INT_INF

structure LargeInt: INTEGER

structure LargeIntArray: MONO_ARRAY

structure LargeIntArray2: MONO_ARRAY2

structure LargeIntArraySlice: MONO_ARRAY_SLICE

structure LargeIntVector: MONO_VECTOR

structure LargeIntVectorSlice: MONO_VECTOR_SLICE

structure LargeReal: REAL

structure LargeRealArray: MONO_ARRAY

structure LargeRealArray2: MONO_ARRAY2

structure LargeRealArraySlice: MONO_ARRAY_SLICE

structure LargeRealVector: MONO_VECTOR

structure LargeRealVectorSlice: MONO_VECTOR_SLICE

structure LargeWord: WORD

structure LargeWordArray: MONO_ARRAY

structure LargeWordArray2: MONO_ARRAY2

structure LargeWordArraySlice: MONO_ARRAY_SLICE

structure LargeWordVector: MONO_VECTOR

structure LargeWordVectorSlice: MONO_VECTOR_SLICE

structure List: LIST

structure ListPair: LIST_PAIR

structure Math: MATH

structure NetHostDB: NET_HOST_DB

structure NetProtDB: NET_PROT_DB

structure NetServDB: NET_SERV_DB

structure OS: OS

structure Option: OPTION

structure PackReal32Big: PACK_REAL

structure PackReal32Little: PACK_REAL

structure PackReal64Big: PACK_REAL

structure PackReal64Little: PACK_REAL

structure PackRealBig: PACK_REAL

structure PackRealLittle: PACK_REAL

structure PackWord16Big: PACK_WORD

structure PackWord16Little: PACK_WORD

structure PackWord32Big: PACK_WORD

structure PackWord32Little: PACK_WORD

structure PackWord64Big: PACK_WORD

structure PackWord64Little: PACK_WORD

structure Position: INTEGER

structure Posix: POSIX

structure Real: REAL

structure RealArray: MONO_ARRAY

structure RealArray2: MONO_ARRAY2

structure RealArraySlice: MONO_ARRAY_SLICE

structure RealVector: MONO_VECTOR

structure RealVectorSlice: MONO_VECTOR_SLICE

structure Real32: REAL

structure Real32Array: MONO_ARRAY

structure Real32Array2: MONO_ARRAY2

structure Real32ArraySlice: MONO_ARRAY_SLICE

structure Real32Vector: MONO_VECTOR

structure Real32VectorSlice: MONO_VECTOR_SLICE

structure Real64: REAL

structure Real64Array: MONO_ARRAY

structure Real64Array2: MONO_ARRAY2

structure Real64ArraySlice: MONO_ARRAY_SLICE

structure Real64Vector: MONO_VECTOR

structure Real64VectorSlice: MONO_VECTOR_SLICE

structure Socket: SOCKET

The Basis Library specification requires functions like Socket.sendVec to raise an exception if they fail. However, on some platforms, sending to a socket that hasn’t yet been connected causes a SIGPIPE signal, which invokes the default signal handler for SIGPIPE and causes the program to terminate. If you want the exception to be raised, you can ignore SIGPIPE by adding the following to your program.
```
let
   open MLton.Signal
in
   setHandler (Posix.Signal.pipe, Handler.ignore)
end
```

structure String: STRING

The String functions do not depend on locale.

structure StringCvt: STRING_CVT

structure Substring: SUBSTRING

structure SysWord: WORD

structure Text: TEXT

structure TextIO: TEXT_IO

structure TextPrimIO: PRIM_IO

structure Time: TIME

structure Timer: TIMER

structure Unix: UNIX

structure UnixSock: UNIX_SOCK

structure Vector: VECTOR

structure VectorSlice: VECTOR_SLICE

structure Word: WORD

structure Word1: WORD

structure Word2: WORD

structure Word3: WORD

structure Word4: WORD

…

structure Word31: WORD

structure Word32: WORD

structure Word64: WORD

structure WordArray: MONO_ARRAY

structure WordArray2: MONO_ARRAY2

structure WordArraySlice: MONO_ARRAY_SLICE

structure WordVectorSlice: MONO_VECTOR_SLICE

structure WordVector: MONO_VECTOR

structure Word8Array: MONO_ARRAY

structure Word8Array2: MONO_ARRAY2

structure Word8ArraySlice: MONO_ARRAY_SLICE

structure Word8Vector: MONO_VECTOR

structure Word8VectorSlice: MONO_VECTOR_SLICE

structure Word16Array: MONO_ARRAY

structure Word16Array2: MONO_ARRAY2

structure Word16ArraySlice: MONO_ARRAY_SLICE

structure Word16Vector: MONO_VECTOR

structure Word16VectorSlice: MONO_VECTOR_SLICE

structure Word32Array: MONO_ARRAY

structure Word32Array2: MONO_ARRAY2

structure Word32ArraySlice: MONO_ARRAY_SLICE

structure Word32Vector: MONO_VECTOR

structure Word32VectorSlice: MONO_VECTOR_SLICE

structure Word64Array: MONO_ARRAY

structure Word64Array2: MONO_ARRAY2

structure Word64ArraySlice: MONO_ARRAY_SLICE

structure Word64Vector: MONO_VECTOR

structure Word64VectorSlice: MONO_VECTOR_SLICE

Top-level functors

ImperativeIO

PrimIO

StreamIO

MLton’s StreamIO functor takes structures ArraySlice and VectorSlice in addition to the arguments specified in the Basis Library specification.

Type equivalences

The following types are equivalent.

FixedInt = Int64.int
LargeInt = IntInf.int
LargeReal.real = Real64.real
LargeWord = Word64.word

The default int, real, and word types may be set by the -default-type type compile-time option. By default, the following types are equivalent:

int = Int.int = Int32.int
real = Real.real = Real64.real
word = Word.word = Word32.word

Real and Math functions

The Real, Real32, and Real64 modules are implemented using the C math library, so the SML functions will reflect the behavior of the underlying library function. We have made some effort to unify the differences between the math libraries on different platforms, and in particular to handle exceptional cases according to the Basis Library specification. However, there will be differences due to different numerical algorithms and cases we may have missed. Please submit a bug report if you encounter an error in the handling of an exceptional case.

On x86, real arithmetic is implemented internally using 80 bits of precision. Using higher precision for intermediate results in computations can lead to different results than if all the computation is done at 32 or 64 bits. If you require strict IEEE compliance, you can compile with -ieee-fp true, which will cause intermediate results to be stored after each operation. This may cause a substantial performance penalty.