BasisLibrary - MLton Standard ML Compiler (SML Compiler)

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. The official online version of the Basis Library specification is at

http://www.standardml.org/Basis/. We keep a copy at

http://mlton.org/basis/. There is a book that includes all of the online version and more. For a reverse chronological list of changes to the specification, see

http://www.standardml.org/Basis/history.html.

MLton implements all of the required portions of the Basis Library. MLton also implements many of the optional structures. 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.

Below is a complete list of what MLton implements.

Top-level types and constructors
Top-level exception constructors
Top-level values
Overloaded identifiers
Top-level signatures
Top-level structures
Top-level functors
Type equivalences
Real and Math functions

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