## Poly/ML Basis Library

A list of the items in the Poly/ML basis. These are the pre-defined structures, values, types and functors. Many of them are from the Standard Basis Library and are not described in much detail here. The entries that are specific to Poly/ML are explained in greater detail.

### Structures

Array | Array2 | ArraySlice | Asn1 | BinIO | BinPrimIO | Bool | BoolArray
BoolArray2 | BoolVector | Byte | Char | CharArray | CharArray2 | CharArraySlice | CharVector
CharVectorSlice | CInterface | CommandLine | Date | Foreign | General | GenericSock | HashArray
IEEEReal | INetSock | IO | Int | Int32 | IntArray | IntArray2 | IntArraySlice
IntInf | IntVector | IntVectorSlice | LargeInt | LargeReal | LargeWord | List | ListPair
Math | NetHostDB | NetProtDB | NetServDB | Option | OS | PackRealBig | PackRealLittle
PackWord16Big | PackWord16Little | PackWord32Big | PackWord32Little | PackWord8Big | PackWord8Little | PolyML | Position
Posix | Process | Real | RealArray | RealArray2 | RealArraySlice | RealVector | RealVectorSlice
RunCall | RuntimeCalls | Signal | SingleAssignment | SML90 | Socket | String | StringCvt
Substring | SysWord | Text | TextIO | TextPrimIO | Thread | ThreadLib | Time
Timer | Universal | UniversalArray | Unix | UnixSock | Vector | VectorSlice | Weak
Windows | Word | Word8 | Word8Array | Word8Array2 | Word8ArraySlice | Word8Vector | Word8VectorSlice
Word32 | Word64 |  |  |  |  |  |

### Signatures

ARRAY | ARRAY2 | ARRAY_SLICE | ASN1 | BIN_IO | BIT_FLAGS | BOOL | BYTE
CHAR | COMMAND_LINE | DATE | FOREIGN | GENERAL | GENERIC_SOCK | IEEE_REAL | IMPERATIVE_IO
INET_SOCK | IO | INTEGER | INT_INF | 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_FILE_SYS | POSIX_IO | POSIX_PROC_ENV | POSIX_PROCESS | POSIX_SIGNAL | POSIX_SYS_DB | POSIX_TTY | PRIM_IO
REAL | SIGNAL | SML90 | SOCKET | STREAM_IO | STRING | STRING_CVT | SUBSTRING
TEXT | TEXT_IO | TEXT_STREAM_IO | THREAD | TIME | TIMER | UNIX | UNIX_SOCK
VECTOR | VECTOR_SLICE | WEAK | WINDOWS | WORD |  |  |

### Functors

ImperativeIO | PrimIO | StreamIO

### Values

! | :: | := | @ | ^ | app | before | Bind
ceil | chr | Chr | concat | Div | Domain | EQUAL | Empty
exnMessage | exnName | explode | Fail | false | floor | foldl | foldr
getOpt | GREATER | hd | ignore | implode | isSome | length | LESS
map | Match | nil | NONE | not | null | o | ord
Option | Overflow | print | real | ref | rev | round | size
Size | SOME | Span | str | Subscript | substring | tl | true
trunc | use | valOf | vector |  |  |  |

### Types

array | bool | char | exn | int | list | option | order
real | ref | string | substring | unit | vector | word |

### Infixes

    infix  7 * / div mod
    infix  6 + - ^
    infix  4 = <> > >= < <=
    infixr 5 :: @
    infix  3 := o
    infix  0 before

### Standard Basis Library

Poly/ML supports the ML Standard Basis Library. The documentation is available as a book, The Standard ML Basis Library, by Emden Gansner and John Reppy. This is a short overview with specific reference to the implementation in Poly/ML.

    signature GENERAL
    structure General: GENERAL

Mainly standard exceptions. All of the values in the `General` structure are available unqualified at the top level.

    signature OPTION
    structure Option: OPTION

The option type, defined as `datatype 'a option = NONE | SOME of 'a`, together with associated functions. Some of these are available unqualified at the top level.

    signature BOOL
    structure Bool: BOOL

Functions on type bool.

    signature INTEGER
    signature INT_INF
    structure Int: INTEGER
    structure LargeInt: INTEGER
    structure Position: INTEGER
    structure Position: INTEGER
    structure IntInf: INT_INF

`Int`, `LargeInt` and `Position` are the same structure and provide operations on type `int`. In Poly/ML that is an arbitrary precision integer. Poly/ML does not support any fixed precision integers. `IntInf` provides additional functions, such as logical operations on integers. Note: there are functions to compute LCM and GCD in PolyML.IntInf.

Int32 provides a fixed precision 32-bit integer

    signature REAL
    structure Real: REAL
    structure LargeReal: REAL

`Real` and `LargeReal` are the same structure in Poly/ML. They provide functions on type `real`.

    signature MATH
    structure Math: MATH

The mathematical functions on type real.

    signature IEEE_REAL
    structure IEEEReal: IEEE_REAL

Functions to manipulate IEEE real numbers, such as controlling rounding and handling not-a-number.

    signature WORD
    structure Word8: WORD
    structure LargeWord: WORD
    structure SysWord: WORD
    structure Word32: WORD
    structure Word64: WORD

Operations on machine words treated as unsigned quantities. Functions which would overflow simply wrap round. Poly/ML implements Word.word as a 31 bit quantity on 32-bit platforms and a 63 bit quantity on 64-bit platforms. In version 5.5 and earlier LargeWord and SysWord were implemented using a double precision version. From version 5.5.1 they are implemented as 32 and 64-bit versions as Word32 and Word64 respectively. Word64 is only available on 64-bit architectures. SysWord is used in the Windows and Posix structures. Word8.word is an unsigned byte.

    signature CHAR
    structure Char: CHAR

Operations on values of type `char`.

    signature STRING
    structure String: STRING

Operations on values of type `string`.

    signature STRING_CVT
    structure StringCvt: STRING_CVT

Additional string functions used primarily when converting between strings and string representations.

    signature SUBSTRING
    structure Substring: SUBSTRING

Operations on substrings. These are segments of strings defined by a base string, an offset and a length and are designed to allow substrings to be manipulated without the storage overhead of creating the substrings themselves.

    signature TEXT
    structure Text: TEXT

The Text structure collects together various structures related to characters.

    signature LIST
    signature LIST_PAIR
    structure List: LIST
    structure ListPair: LIST_PAIR

Functions on lists and lists of pairs.

    signature VECTOR
    signature ARRAY
    structure Vector: VECTOR
    structure Array: ARRAY

Polymorphic vector and array.

    signature MONO_VECTOR
    signature MONO_ARRAY
    structure Word8Vector: MONO_VECTOR
    structure CharVector: MONO_VECTOR
    structure BoolVector: MONO_VECTOR
    structure IntVector: MONO_VECTOR
    structure RealVector: MONO_VECTOR
    structure Word8Array: MONO_ARRAY
    structure CharArray: MONO_ARRAY
    structure BoolArray: MONO_ARRAY
    structure IntArray: MONO_ARRAY
    structure RealArray: MONO_ARRAY

Monomorphic vectors and arrays. Generally these are designed to be storage-efficient at the expense of time. `CharVector.vector` is the same as string so provides vector operations on strings. `Word8Vector.vector` is used in various places throughout the library as a binary analogue of string. `BoolVector` and `BoolArray` use single bits for each value.

    signature ARRAY2
    structure Array2: ARRAY2
    signature MONO_ARRAY2
    structure Word8Array2: MONO_ARRAY2
    structure CharArray2: MONO_ARRAY2
    structure BoolArray2: MONO_ARRAY2
    structure IntArray2: MONO_ARRAY2
    structure RealArray2: MONO_ARRAY2

Two dimensional arrays.

    signature VECTOR_SLICE
    signature ARRAY_SLICE
    structure VectorSlice: VECTOR_SLICE
    structure ArraySlice: ARRAY_SLICE

Polymorphic subvectors and subarrays.

    signature MONO_VECTOR_SLICE
    signature MONO_ARRAY_SLICE
    structure Word8VectorSlice: MONO_VECTOR_SLICE
    structure CharVectorSlice: MONO_VECTOR_SLICE
    structure IntVectorSlice: MONO_VECTOR_SLICE
    structure RealVectorSlice: MONO_VECTOR_SLICE
    structure Word8ArraySlice: MONO_ARRAY_SLICE
    structure CharArraySlice: MONO_ARRAY_SLICE
    structure IntArraySlice: MONO_ARRAY_SLICE
    structure RealArraySlice: MONO_ARRAY_SLICE

Monomorphic subvectors and subarrays.

    signature BYTE
    structure Byte: BYTE

Provides functions to convert between characters and `Word8.word` values and between strings and `Word8Vector.vector` values. In Poly/ML these can generally be implemented as a cast so do not incur any time or space overhead.

    signature COMMAND_LINE
    structure CommandLine: COMMAND_LINE

Access to the command line and arguments. Does not include arguments taken by the run-time system.

    signature TIME
    structure Time: TIME

Functions on times. Poly/ML implements this as microseconds since 1st January 1970 in Unix and nanoseconds since 1st January 1601 (FILETIME) in Windows.

    signature DATE
    structure Date: DATE

Functions on dates including conversions to and from `Time.time`.

    signature TIMER
    structure Timer: TIMER

Functions to return CPU time and garbage collection time.

    signature PACK_WORD
    structure PackWord8Big: PACK_WORD
    structure PackWord8Little: PACK_WORD
    structure PackWord16Big: PACK_WORD
    structure PackWord16Little: PACK_WORD
    structure PackWord32Big: PACK_WORD
    structure PackWord32Little: PACK_WORD
    signature PACK_REAL
    structure PackRealBig: PACK_REAL
    structure PackRealLittle: PACK_REAL

Operations to pack and unpack integers and reals into byte vectors.

    signature IO
    structure IO: IO

The `IO` structure contains types and exceptions used within the other IO structures.

    structure TextIO: sig ... end

The `TextIO` structure is the top level of the IO stack for textual input and output. This is level likely to be used most often. Input and output are side-effecting and, if necessary, characters such as newlines are translated between the ML and operating system codes.

    signature TEXT_STREAM_IO
    structure TextIO.StreamIO: TEXT_STREAM_IO

This substructure access to a lower level of textual input and output. Output is not significantly different from that of `TextIO` but input is applicative rather than imperative. In essence this means that input functions return both a value, character or string, and a new stream. Reading from the new stream continues the input, reading from the original stream returns the previous value. This is intended to simplify backtracking in parsing and works particularly well with the `scan` functions in the library.

    signature BIN_IO
    structure BinIO: BIN_IO

`BinIO` is similar to `TextIO` but for binary input and output. While `TextIO` works on types `char` and `string`, `BinIO` works on bytes (`Word8.word`) and byte vectors (`Word8Vector.vector`). Unlike TextIO binary I/O does not perform any translation of characters.
`BinIO.StreamIO: STREAM_IO`
Similar to `TextIO.StreamIO`.

    signature PRIM_IO
    structure BinPrimIO: PRIM_IO
    structure TextPrimIO: PRIM_IO

The primitive I/O functions are the lowest level of the stack. They provide access to the underlying readers and writers.

    signature IMPERATIVE_IO
    functor ImperativeIO ( ... ): IMPERATIVE_IO
    signature STREAM_IO
    functor StreamIO ( ... ): STREAM_IO
    signature PRIM_IO
    functor PrimIO ( ... ): PRIM_IO

These functors can be used to build new stacks to provide input and output on data structures other than characters and bytes.

    signature OS
    signature OS_FILE_SYS
    signature OS_IO
    signature OS_PATH
    signature OS_PROCESS
    structure OS: OS

The `OS` structure contains a large number of functions for accessing operating system facilities. Most of them are grouped into substructures. `OS.FileSys` contains functions for examining directories and files. `OS.Path` operates on file path names. `OS.Process` provides functions to terminate the current ML program with various results, examine the environment and to run sub-processes. `OS.IO` provides the ability to poll a set of file descriptors.

    signature COMMAND_LINE
    structure CommandLine: COMMAND_LINE

CommandLine provides access to the command line arguments. Note that the Poly/ML run-time system recognises and removes various arguments and these are not included in the arguments available to the ML program.

    signature SOCKET
    structure Socket: SOCKET

Operations on sockets, providing access to network facilities from ML. `Socket` does not actually contain functions to create sockets. Instead these are found in the `INetSock`, `UnixSock` and `GenericSock` structures.

    signature INET_SOCK
    structure INetSock: INET_SOCK

Creates internet domain sockets and provides functions on internet addresses.

    signature UNIX_SOCK
    structure UnixSock: UNIX_SOCK

Creates Unix domain (local) sockets. This structure is not provided in the Windows implementation.

    signature GENERIC_SOCK
    structure GenericSock: GENERIC_SOCK

Can be used to create sockets in any domain supported by the system.

    signature NET_HOST_DB
    structure NetHostDB: NET_HOST_DB
    signature NET_PROT_DB
    structure NetProtDB: NET_PROT_DB
    signature NET_SERV_DB
    structure NetServDB: NET_SERV_DB

Look up names in various tables. `NetHostDB` looks up an internet address using DNS. `NetProtDB` looks up a protocol in (on Unix) /etc/protocols. `NetServDB` looks up a service in (on Unix) /etc/services.

    signature UNIX
    structure Unix: UNIX

Provides access to Unix-specific functions, such as forking a process. This structure is not provided in the Windows implementation.

    signature POSIX
    signature POSIX_ERROR
    signature POSIX_SIGNAL
    signature POSIX_PROCESS
    signature POSIX_PROC_ENV
    signature POSIX_FILE_SYS
    signature POSIX_IO
    signature POSIX_SYS_DB
    signature POSIX_TTY
    structure Posix: POSIX

Provides access to a wide range of Unix system calls. This structure and the signatures are not provided in the Windows implementation.

    signature WINDOWS
    structure Windows: WINDOWS

Windows-specific functions. This structure is not provided in the Unix implementations.

### Poly/ML Extensions

There are a number of extensions to Poly/ML. Most of these are described in greater detail in other documents.

    structure Asn1: ASN1
    signature ASN1

Operations on ASN1 binary encoding. There are functions to help convert between tree structures and byte vectors. This is experimental.

    structure CInterface
    signature CInterfaceSig

This is the older version of the foreign-function interface. The new version is in the Foreign structure. See the full documentation.

    structure Foreign
    signature FOREIGN

This is the new version of the foreign-function interface.

    structure HashArray

Provides a hash-table type and operations.

    structure PolyML

Contains a large number of operations specific to Poly/ML. See here for full information.

    structure Process

This is the original implementation of parallelism in Poly/ML. It has now been reimplemented using the Thread structure. It is provided for backwards compatibility only.

    structure RunCall
    structure RuntimeCalls

RunCall contains various low-level operations for interface to the run-time system. RuntimeCalls contains symbolic definitions for entry points to the run-time system. These structures are intended only for use in the basis library itself and should not be used in user code unless absolutely necessary. It is very easy to use them in a way that will cause a crash or break the garbage-collector resulting in a failure at some point in the future.

    structure Signal
    signature SIGNAL

Provides a way of handling Unix-style signals. On Windows this deals only with the interrupt signal, SIGINT. See here for full information.

    structure SingleAssignment

Provides references that can only be assigned to once. Once a variable has been assigned a value that is fixed and further attempts to assign a new value result in an exception. The main reason for providing this is that once the value has been assigned it is marked as an immutable cell and this has advantages in efficiency for the garbage collector. Locked cells that contain the same value can be shared with PolyML.shareCommonData. See here for more information.

    structure SML90: SML90
    signature SML90

Provides backwards compatibility with ML90. This was included in an earlier draft of the Standard Basis Library but was withdrawn before the final release.

    structure Thread: THREAD
    signature THREAD
    structure ThreadLib

The Thread structure provides a way of creating parallel threads and synchronising between them. ThreadLib is an extension library for the Thread structure. See here for full information.

    structure Universal
    structure UniversalArray

The Universal structure provides support for a universal union type that can contain a value of any type. It is used in various library functions. See here for full information.

    structure Weak
    signature WEAK

Provides the ability to construct weak references, that is references that can be used to detect when all other pointers to the reference have been removed by the garbage collector. They are intended to allow a program to recover resources when they are no longer reachable. See here for full information.