doc/guide/src/BasisLibrary.adoc

   1 BasisLibrary
   2 ============
   3 :toc:
   4
   5 The <:StandardML:Standard ML> Basis Library is a collection of modules
   6 dealing with basic types, input/output, OS interfaces, and simple
   7 datatypes.  It is intended as a portable library usable across all
   8 implementations of SML.  For the official online version of the Basis
   9 Library specification, see http://www.standardml.org/Basis.
  10 <!Cite(GansnerReppy04, The Standard ML Basis Library)> is a book
  11 version that includes all of the online version and more.  For a
  12 reverse chronological list of changes to the specification, see
  13 http://www.standardml.org/Basis/history.html.
  14
  15 MLton implements all of the required portions of the Basis Library.
  16 MLton also implements many of the optional structures.  You can obtain
  17 a complete and current list of what's available using
  18 `mlton -show-basis` (see <:ShowBasis:>).  By default, MLton makes the
  19 Basis Library available to user programs.  You can also
  20 <:MLBasisAvailableLibraries:access the Basis Library> from
  21 <:MLBasis: ML Basis> files.
  22
  23 Below is a complete list of what MLton implements.
  24
  25 == Top-level types and constructors ==
  26
  27 `eqtype 'a array`
  28
  29 `datatype bool = false | true`
  30
  31 `eqtype char`
  32
  33 `type exn`
  34
  35 `eqtype int`
  36
  37 ++datatype 'a list = nil | {two-colons} of ('a * 'a list)++
  38
  39 `datatype 'a option = NONE | SOME of 'a`
  40
  41 `datatype order = EQUAL | GREATER | LESS`
  42
  43 `type real`
  44
  45 `datatype 'a ref = ref of 'a`
  46
  47 `eqtype string`
  48
  49 `type substring`
  50
  51 `eqtype unit`
  52
  53 `eqtype 'a vector`
  54
  55 `eqtype word`
  56
  57 == Top-level exception constructors ==
  58
  59 `Bind`
  60
  61 `Chr`
  62
  63 `Div`
  64
  65 `Domain`
  66
  67 `Empty`
  68
  69 `Fail of string`
  70
  71 `Match`
  72
  73 `Option`
  74
  75 `Overflow`
  76
  77 `Size`
  78
  79 `Span`
  80
  81 `Subscript`
  82
  83 == Top-level values ==
  84
  85 MLton does not implement the optional top-level value
  86 `use: string -> unit`, which conflicts with whole-program
  87 compilation because it allows new code to be loaded dynamically.
  88
  89 MLton implements all other top-level values:
  90
  91 `!`,
  92 `:=`,
  93 `<>`,
  94 `=`,
  95 `@`,
  96 `^`,
  97 `app`,
  98 `before`,
  99 `ceil`,
 100 `chr`,
 101 `concat`,
 102 `exnMessage`,
 103 `exnName`,
 104 `explode`,
 105 `floor`,
 106 `foldl`,
 107 `foldr`,
 108 `getOpt`,
 109 `hd`,
 110 `ignore`,
 111 `implode`,
 112 `isSome`,
 113 `length`,
 114 `map`,
 115 `not`,
 116 `null`,
 117 `o`,
 118 `ord`,
 119 `print`,
 120 `real`,
 121 `rev`,
 122 `round`,
 123 `size`,
 124 `str`,
 125 `substring`,
 126 `tl`,
 127 `trunc`,
 128 `valOf`,
 129 `vector`
 130
 131 == Overloaded identifiers ==
 132
 133 `*`,
 134 `+`,
 135 `-`,
 136 `/`,
 137 `<`,
 138 `<=`,
 139 `>`,
 140 `>=`,
 141 `~`,
 142 `abs`,
 143 `div`,
 144 `mod`
 145
 146 == Top-level signatures ==
 147
 148 `ARRAY`
 149
 150 `ARRAY2`
 151
 152 `ARRAY_SLICE`
 153
 154 `BIN_IO`
 155
 156 `BIT_FLAGS`
 157
 158 `BOOL`
 159
 160 `BYTE`
 161
 162 `CHAR`
 163
 164 `COMMAND_LINE`
 165
 166 `DATE`
 167
 168 `GENERAL`
 169
 170 `GENERIC_SOCK`
 171
 172 `IEEE_REAL`
 173
 174 `IMPERATIVE_IO`
 175
 176 `INET_SOCK`
 177
 178 `INTEGER`
 179
 180 `INT_INF`
 181
 182 `IO`
 183
 184 `LIST`
 185
 186 `LIST_PAIR`
 187
 188 `MATH`
 189
 190 `MONO_ARRAY`
 191
 192 `MONO_ARRAY2`
 193
 194 `MONO_ARRAY_SLICE`
 195
 196 `MONO_VECTOR`
 197
 198 `MONO_VECTOR_SLICE`
 199
 200 `NET_HOST_DB`
 201
 202 `NET_PROT_DB`
 203
 204 `NET_SERV_DB`
 205
 206 `OPTION`
 207
 208 `OS`
 209
 210 `OS_FILE_SYS`
 211
 212 `OS_IO`
 213
 214 `OS_PATH`
 215
 216 `OS_PROCESS`
 217
 218 `PACK_REAL`
 219
 220 `PACK_WORD`
 221
 222 `POSIX`
 223
 224 `POSIX_ERROR`
 225
 226 `POSIX_FILE_SYS`
 227
 228 `POSIX_IO`
 229
 230 `POSIX_PROCESS`
 231
 232 `POSIX_PROC_ENV`
 233
 234 `POSIX_SIGNAL`
 235
 236 `POSIX_SYS_DB`
 237
 238 `POSIX_TTY`
 239
 240 `PRIM_IO`
 241
 242 `REAL`
 243
 244 `SOCKET`
 245
 246 `STREAM_IO`
 247
 248 `STRING`
 249
 250 `STRING_CVT`
 251
 252 `SUBSTRING`
 253
 254 `TEXT`
 255
 256 `TEXT_IO`
 257
 258 `TEXT_STREAM_IO`
 259
 260 `TIME`
 261
 262 `TIMER`
 263
 264 `UNIX`
 265
 266 `UNIX_SOCK`
 267
 268 `VECTOR`
 269
 270 `VECTOR_SLICE`
 271
 272 `WORD`
 273
 274 == Top-level structures ==
 275
 276 `structure Array: ARRAY`
 277
 278 `structure Array2: ARRAY2`
 279
 280 `structure ArraySlice: ARRAY_SLICE`
 281
 282 `structure BinIO: BIN_IO`
 283
 284 `structure BinPrimIO: PRIM_IO`
 285
 286 `structure Bool: BOOL`
 287
 288 `structure BoolArray: MONO_ARRAY`
 289
 290 `structure BoolArray2: MONO_ARRAY2`
 291
 292 `structure BoolArraySlice: MONO_ARRAY_SLICE`
 293
 294 `structure BoolVector: MONO_VECTOR`
 295
 296 `structure BoolVectorSlice: MONO_VECTOR_SLICE`
 297
 298 `structure Byte: BYTE`
 299
 300 `structure Char: CHAR`
 301
 302 * `Char` characters correspond to ISO-8859-1.  The `Char` functions do not depend on locale.
 303
 304 `structure CharArray: MONO_ARRAY`
 305
 306 `structure CharArray2: MONO_ARRAY2`
 307
 308 `structure CharArraySlice: MONO_ARRAY_SLICE`
 309
 310 `structure CharVector: MONO_VECTOR`
 311
 312 `structure CharVectorSlice: MONO_VECTOR_SLICE`
 313
 314 `structure CommandLine: COMMAND_LINE`
 315
 316 `structure Date: DATE`
 317
 318 * `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.
 319
 320 `structure FixedInt: INTEGER`
 321
 322 `structure General: GENERAL`
 323
 324 `structure GenericSock: GENERIC_SOCK`
 325
 326 `structure IEEEReal: IEEE_REAL`
 327
 328 `structure INetSock: INET_SOCK`
 329
 330 `structure IO: IO`
 331
 332 `structure Int: INTEGER`
 333
 334 `structure Int1: INTEGER`
 335
 336 `structure Int2: INTEGER`
 337
 338 `structure Int3: INTEGER`
 339
 340 `structure Int4: INTEGER`
 341
 342 ...
 343
 344 `structure Int31: INTEGER`
 345
 346 `structure Int32: INTEGER`
 347
 348 `structure Int64: INTEGER`
 349
 350 `structure IntArray: MONO_ARRAY`
 351
 352 `structure IntArray2: MONO_ARRAY2`
 353
 354 `structure IntArraySlice: MONO_ARRAY_SLICE`
 355
 356 `structure IntVector: MONO_VECTOR`
 357
 358 `structure IntVectorSlice: MONO_VECTOR_SLICE`
 359
 360 `structure Int8: INTEGER`
 361
 362 `structure Int8Array: MONO_ARRAY`
 363
 364 `structure Int8Array2: MONO_ARRAY2`
 365
 366 `structure Int8ArraySlice: MONO_ARRAY_SLICE`
 367
 368 `structure Int8Vector: MONO_VECTOR`
 369
 370 `structure Int8VectorSlice: MONO_VECTOR_SLICE`
 371
 372 `structure Int16: INTEGER`
 373
 374 `structure Int16Array: MONO_ARRAY`
 375
 376 `structure Int16Array2: MONO_ARRAY2`
 377
 378 `structure Int16ArraySlice: MONO_ARRAY_SLICE`
 379
 380 `structure Int16Vector: MONO_VECTOR`
 381
 382 `structure Int16VectorSlice: MONO_VECTOR_SLICE`
 383
 384 `structure Int32: INTEGER`
 385
 386 `structure Int32Array: MONO_ARRAY`
 387
 388 `structure Int32Array2: MONO_ARRAY2`
 389
 390 `structure Int32ArraySlice: MONO_ARRAY_SLICE`
 391
 392 `structure Int32Vector: MONO_VECTOR`
 393
 394 `structure Int32VectorSlice: MONO_VECTOR_SLICE`
 395
 396 `structure Int64Array: MONO_ARRAY`
 397
 398 `structure Int64Array2: MONO_ARRAY2`
 399
 400 `structure Int64ArraySlice: MONO_ARRAY_SLICE`
 401
 402 `structure Int64Vector: MONO_VECTOR`
 403
 404 `structure Int64VectorSlice: MONO_VECTOR_SLICE`
 405
 406 `structure IntInf: INT_INF`
 407
 408 `structure LargeInt: INTEGER`
 409
 410 `structure LargeIntArray: MONO_ARRAY`
 411
 412 `structure LargeIntArray2: MONO_ARRAY2`
 413
 414 `structure LargeIntArraySlice: MONO_ARRAY_SLICE`
 415
 416 `structure LargeIntVector: MONO_VECTOR`
 417
 418 `structure LargeIntVectorSlice: MONO_VECTOR_SLICE`
 419
 420 `structure LargeReal: REAL`
 421
 422 `structure LargeRealArray: MONO_ARRAY`
 423
 424 `structure LargeRealArray2: MONO_ARRAY2`
 425
 426 `structure LargeRealArraySlice: MONO_ARRAY_SLICE`
 427
 428 `structure LargeRealVector: MONO_VECTOR`
 429
 430 `structure LargeRealVectorSlice: MONO_VECTOR_SLICE`
 431
 432 `structure LargeWord: WORD`
 433
 434 `structure LargeWordArray: MONO_ARRAY`
 435
 436 `structure LargeWordArray2: MONO_ARRAY2`
 437
 438 `structure LargeWordArraySlice: MONO_ARRAY_SLICE`
 439
 440 `structure LargeWordVector: MONO_VECTOR`
 441
 442 `structure LargeWordVectorSlice: MONO_VECTOR_SLICE`
 443
 444 `structure List: LIST`
 445
 446 `structure ListPair: LIST_PAIR`
 447
 448 `structure Math: MATH`
 449
 450 `structure NetHostDB: NET_HOST_DB`
 451
 452 `structure NetProtDB: NET_PROT_DB`
 453
 454 `structure NetServDB: NET_SERV_DB`
 455
 456 `structure OS: OS`
 457
 458 `structure Option: OPTION`
 459
 460 `structure PackReal32Big: PACK_REAL`
 461
 462 `structure PackReal32Little: PACK_REAL`
 463
 464 `structure PackReal64Big: PACK_REAL`
 465
 466 `structure PackReal64Little: PACK_REAL`
 467
 468 `structure PackRealBig: PACK_REAL`
 469
 470 `structure PackRealLittle: PACK_REAL`
 471
 472 `structure PackWord16Big: PACK_WORD`
 473
 474 `structure PackWord16Little: PACK_WORD`
 475
 476 `structure PackWord32Big: PACK_WORD`
 477
 478 `structure PackWord32Little: PACK_WORD`
 479
 480 `structure PackWord64Big: PACK_WORD`
 481
 482 `structure PackWord64Little: PACK_WORD`
 483
 484 `structure Position: INTEGER`
 485
 486 `structure Posix: POSIX`
 487
 488 `structure Real: REAL`
 489
 490 `structure RealArray: MONO_ARRAY`
 491
 492 `structure RealArray2: MONO_ARRAY2`
 493
 494 `structure RealArraySlice: MONO_ARRAY_SLICE`
 495
 496 `structure RealVector: MONO_VECTOR`
 497
 498 `structure RealVectorSlice: MONO_VECTOR_SLICE`
 499
 500 `structure Real32: REAL`
 501
 502 `structure Real32Array: MONO_ARRAY`
 503
 504 `structure Real32Array2: MONO_ARRAY2`
 505
 506 `structure Real32ArraySlice: MONO_ARRAY_SLICE`
 507
 508 `structure Real32Vector: MONO_VECTOR`
 509
 510 `structure Real32VectorSlice: MONO_VECTOR_SLICE`
 511
 512 `structure Real64: REAL`
 513
 514 `structure Real64Array: MONO_ARRAY`
 515
 516 `structure Real64Array2: MONO_ARRAY2`
 517
 518 `structure Real64ArraySlice: MONO_ARRAY_SLICE`
 519
 520 `structure Real64Vector: MONO_VECTOR`
 521
 522 `structure Real64VectorSlice: MONO_VECTOR_SLICE`
 523
 524 `structure Socket: SOCKET`
 525
 526 * The Basis Library specification requires functions like
 527 `Socket.sendVec` to raise an exception if they fail.  However, on some
 528 platforms, sending to a socket that hasn't yet been connected causes a
 529 `SIGPIPE` signal, which invokes the default signal handler for
 530 `SIGPIPE` and causes the program to terminate.  If you want the
 531 exception to be raised, you can ignore `SIGPIPE` by adding the
 532 following to your program.
 533 +
 534 [source,sml]
 535 ----
 536 let
 537    open MLton.Signal
 538 in
 539    setHandler (Posix.Signal.pipe, Handler.ignore)
 540 end
 541 ----
 542
 543 `structure String: STRING`
 544
 545 * The `String` functions do not depend on locale.
 546
 547 `structure StringCvt: STRING_CVT`
 548
 549 `structure Substring: SUBSTRING`
 550
 551 `structure SysWord: WORD`
 552
 553 `structure Text: TEXT`
 554
 555 `structure TextIO: TEXT_IO`
 556
 557 `structure TextPrimIO: PRIM_IO`
 558
 559 `structure Time: TIME`
 560
 561 `structure Timer: TIMER`
 562
 563 `structure Unix: UNIX`
 564
 565 `structure UnixSock: UNIX_SOCK`
 566
 567 `structure Vector: VECTOR`
 568
 569 `structure VectorSlice: VECTOR_SLICE`
 570
 571 `structure Word: WORD`
 572
 573 `structure Word1: WORD`
 574
 575 `structure Word2: WORD`
 576
 577 `structure Word3: WORD`
 578
 579 `structure Word4: WORD`
 580
 581 ...
 582
 583 `structure Word31: WORD`
 584
 585 `structure Word32: WORD`
 586
 587 `structure Word64: WORD`
 588
 589 `structure WordArray: MONO_ARRAY`
 590
 591 `structure WordArray2: MONO_ARRAY2`
 592
 593 `structure WordArraySlice: MONO_ARRAY_SLICE`
 594
 595 `structure WordVectorSlice: MONO_VECTOR_SLICE`
 596
 597 `structure WordVector: MONO_VECTOR`
 598
 599 `structure Word8Array: MONO_ARRAY`
 600
 601 `structure Word8Array2: MONO_ARRAY2`
 602
 603 `structure Word8ArraySlice: MONO_ARRAY_SLICE`
 604
 605 `structure Word8Vector: MONO_VECTOR`
 606
 607 `structure Word8VectorSlice: MONO_VECTOR_SLICE`
 608
 609 `structure Word16Array: MONO_ARRAY`
 610
 611 `structure Word16Array2: MONO_ARRAY2`
 612
 613 `structure Word16ArraySlice: MONO_ARRAY_SLICE`
 614
 615 `structure Word16Vector: MONO_VECTOR`
 616
 617 `structure Word16VectorSlice: MONO_VECTOR_SLICE`
 618
 619 `structure Word32Array: MONO_ARRAY`
 620
 621 `structure Word32Array2: MONO_ARRAY2`
 622
 623 `structure Word32ArraySlice: MONO_ARRAY_SLICE`
 624
 625 `structure Word32Vector: MONO_VECTOR`
 626
 627 `structure Word32VectorSlice: MONO_VECTOR_SLICE`
 628
 629 `structure Word64Array: MONO_ARRAY`
 630
 631 `structure Word64Array2: MONO_ARRAY2`
 632
 633 `structure Word64ArraySlice: MONO_ARRAY_SLICE`
 634
 635 `structure Word64Vector: MONO_VECTOR`
 636
 637 `structure Word64VectorSlice: MONO_VECTOR_SLICE`
 638
 639 == Top-level functors ==
 640
 641 `ImperativeIO`
 642
 643 `PrimIO`
 644
 645 `StreamIO`
 646
 647 * MLton's `StreamIO` functor takes structures `ArraySlice` and
 648 `VectorSlice` in addition to the arguments specified in the Basis
 649 Library specification.
 650
 651 == Type equivalences ==
 652
 653 The following types are equivalent.
 654 ----
 655 FixedInt = Int64.int
 656 LargeInt = IntInf.int
 657 LargeReal.real = Real64.real
 658 LargeWord = Word64.word
 659 ----
 660
 661 The default `int`, `real`, and `word` types may be set by the
 662 ++-default-type __type__++ <:CompileTimeOptions: compile-time option>.
 663 By default, the following types are equivalent:
 664 ----
 665 int = Int.int = Int32.int
 666 real = Real.real = Real64.real
 667 word = Word.word = Word32.word
 668 ----
 669
 670 == Real and Math functions ==
 671
 672 The `Real`, `Real32`, and `Real64` modules are implemented
 673 using the `C` math library, so the SML functions will reflect the
 674 behavior of the underlying library function.  We have made some effort
 675 to unify the differences between the math libraries on different
 676 platforms, and in particular to handle exceptional cases according to
 677 the Basis Library specification.  However, there will be differences
 678 due to different numerical algorithms and cases we may have missed.
 679 Please submit a <:Bug:bug report> if you encounter an error in
 680 the handling of an exceptional case.
 681
 682 On x86, real arithmetic is implemented internally using 80 bits of
 683 precision.  Using higher precision for intermediate results in
 684 computations can lead to different results than if all the computation
 685 is done at 32 or 64 bits.  If you require strict IEEE compliance, you
 686 can compile with `-ieee-fp true`, which will cause intermediate
 687 results to be stored after each operation.  This may cause a
 688 substantial performance penalty.