:version: 2024.1
:date: May 17, 2024
:dist-dir: https://smlnj.org/dist/working/{version}/
:history: {dist-dir}HISTORY.html
:issue-base: https://github.com/smlnj/smlnj/issues
:legacy-issue-base: https://github.com/smlnj/legacy/issues
:pull-base: https://github.com/smlnj/smlnj/pull
:legacy-pull-base: https://github.com/smlnj/legacy/pull/
:stem: latexmath
:source-highlighter: pygments
:stylesheet: release-notes.css
:notitle:

= Standard ML of New Jersey Release Notes

[subs=attributes]
++++
<div class="smlnj-banner">
  <span class="title"> Standard ML of New Jersey <br/> Release Notes </span>
  <br/> <br/>
  <span class="subtitle"> Version {version} <br/> {date} </span>
</div>
++++

''''''''
--
SML/NJ HOME::
  https://www.smlnj.org/index.html[[.tt]#https://smlnj.org#]
FILES::
  {dist-dir}index.html[[.tt]#{dist-dir}#]
--
''''''''

== Summary

This patch release incorporates a large number of bug fixes and improvements
from the "legacy" version , including implementing some missing features
from the https://smlfamily.github.io/Basis/[*Standard ML Basis Library*] and
improvements to the *SML/NJ Library*.

== Details

// **** details: include those sections that are relevant

=== CM

* The *system/cmb-make* script now runs with the `CM_VERBOSE` environment variable
  set to `false` by default (use the `-verbose` option for the old behavior).  It
  also now sets the `PATH` environment variable to include the directory where the
  *sml* command lives when it is given as an argument to *cmb-make*.

=== Basis Library

* Complete rewrite of the mechanisms used to implement conversions
  between strings and reals.  As part of this rewrite, we implemented the
  support for the `StringCvt.EXACT` formatting mode and implemented the
  missing `Real.toDecimal`/`fromDecimal` functions.  The real-string
  conversions is based on the https://github.com/ulfjack/ryu[Ryu library]
  and associated https://doi.org/10.1145/3296979.3192369[PLDI paper]
  by Ulf Adams.

* Added missing implementation of `Real64.nextAfter` function.

* Added `Unsafe.Real64` structure that implements bit casts between
  double-precision reals and 64-bit words.

=== SML/NJ Library

In addition to the bug fixes noted below, the following improvements
made to the **SML/NJ Library**:

* Rewrote the *JSON* parsers to work directly on the input source (instead of
  using a ML-ulex lexer.  This change fixes {issue-base}/284[Issue #284 (ML-ULex's
  memoization causes massive performance penalties for *JSON* parsing).  For
  the `data.json` file mentioned in the issue, parsing is about eight times
  faster, while the speedup is even greater for the `huge.json` file.

* Added the `JSONDecode` structure to the *JSON* library.  This module implements
  a set of combinators (inspired by the *Elm* `JSON.Decode` module)
  for decoding *JSON* values.

* Added `insertWith`, `insertWithi`, and `findAndRemove` operations to the
  `HASH_TABLE` and `MONO_HASH_TABLE` interfaces (and corresponding
  implementations).

* Fixed the error checking and documentation for the `subArray` function
  in the `DynamicArray` structure and `DynamicArrayFn` functor.

* Fixes to the `subArray` and `truncate` functions in the dynamic array
  implementation (both structure `DynamicArray` and functor `DynamicArrayFn`).

* Add `EditDistance` module to utility library.

* Reverted the change to the `JSON.json` datatype from 2023.1 by removing
  the `INTLIT of string` constructor.  We decided to take a more general
  approach to handling literals that will be included in a future version
  of the JSON library.

== Bugs

Here is a list of the issues that are fixed (or closed) with this release.

[.buglist,cols="^1,<15",strips="none",options="header"]
|=======
| Issue
| Description
| [.bugid]#279#
| {issue-base}/279["Unable to build LLVM" error with 2023.1]
| [.bugid]#280#
| {pull-base}/280[`DynamicArray.subArray` creates array with length bound+1]
| [.bugid]#281#
| {issue-base}/281[Support forward-slash ("/") as a separator in the Windows implementation of `OS.Path`]
| [.bugid]#288#
| {issue-base}/288[Incorrect printing of source code in error message]
|=======

We also fixed the following bugs that did not have issues
associated with them (or were bug fixes ported from the legacy
repository):
--
* {legacy-issue-base}/194[Issue #194 (Incorrect formatting of real number)]

* {legacy-issue-base}/269[Issue #269 (`Real.realMod` and
  `Real.split` produce incorrect result for values close to zero)]

* {legacy-issue-base}/280[Support forward-slash ("/") as a separator in the Windows
  implementation of `OS.Path`]

* {legacy-issue-base}/283[Issue #283 (`TextIO.inputAll`
  segfaults when reading 980M file)].

* {legacy-issue-base}/284[ML-ULex's memozation causes massive performance
  penalties for JSON parsing]

* {legacy-issue-base}/285[Unmatched specification in opaque signature ascription
  causes uncaught exception]

* {legacy-issue-base}/286[Get "fgrep is obsolescent" when run *sml* on Fedora]

* {legacy-issue-base}/287[The word literal `0wx80000000` is incorrectly converted
  to `0wx7FFFFFFF80000000`]

* {legacy-issue-base}/289[Uncaught `Bind` exception in compiler with opaque
  signature matching]

* {legacy-issue-base}/290[`Random.realRand` returns far smaller value than unity]

* {legacy-issue-base}/295[CM cannot find tools when using cmb-make to compile
  the compiler]

* {legacy-issue-base}/296[The `fromDecimal` and `toDecimal` functions in
  the `Real` structure are not implemented]

* {legacy-issue-base}/297[Additional operations for the `MONO_HASH_TABLE` interface]

* {legacy-issue-base}/300[Issue #300 (``PackReal64``{``Big``,``Little``}``.update``
  is not implemented)].

* The implementations of `PackWord64Little.update` and `PackWord64Big.update`
  were swapped on 64-bit platforms.
--

== Supported systems

We believe that SML/NJ will build and run on the following systems, but have only
tested some of them:

[.support-table,cols="^2s,^4v,^3v",options="header",strips="none"]
|=======
| Architecture | Operating System | Status
| AMD64 | |
| | macOS 11 (Big Sur) |
| | macOS 12 (Monterey) | Tested
| | macOS 13 (Ventura) | Tested
| | macOS 14 (Sonoma) | Tested
| | Ubuntu 20.04.6 LTS | Tested
| | Ubuntu 22.04.2 LTS | Tested
| {nbsp} | |
|=======
