README

Extensions to, and bugfixes for, the ATS2 prelude.
--------------------------------------------------

* Expanded support for integer types, and workarounds for
  bugs. Changes include at least the following:

    - I have added intmax and uintmax.

    - I have worked around bugs in g1 versions of comparisons with
      zero.

    - I have tightened the postconditions of g1 versions of mod and
      nmod.

    - I have expanded the set of integer power routines, and implement
      pre-compiled versions that are loop-free. (The behavior when
      there is signed integer overflow may differ from that of the
      prelude. I consider this unimportant, because signed integer
      overflow is a bad thing.)

    - I have added ‘true Euclidean division’ of signed integers,
      where the remainder is always non-negative.

    - I have added gcd.

    - I have added ‘count trailing zeros’, ‘find first set’, ‘find
      last set’, ‘population count’.

* Expanded support for floating point, and workarounds for bugs.

* Support for the following floating point types: float16, float32,
  float64, float128, float16x float32x, float64x, float128x,
  decimal32, decimal64, decimal128, decimal64x, decimal128x. Your C
  compiler and libraries are likely to support some of these but not
  others, in varying degrees. ¶ Footnote: On AMD64, the ldouble type
  is stored on 128-bit boundaries, but it is NOT a 128-bit floating
  point type. It is an 80-bit floating point type, which is stored on
  32-bit boundaries on x86. If you want quad precision on AMD64, use
  float128 (which requires libraries that come with GCC).

* 32+32-bit fixed point, treated as if it were floating point
  (g0float).

* Optionally: exact rationals, via the GNU Multiple Precision
  Arithmetic Library (GMP). These are a nonlinear type (for garbage
  collection), and are treated as if they were floating point
  (g0float). ¶ The exact rationals support ‘big integer’ operations on
  their numerators, and thus you can represent a big integer as an
  exrat with denominator one. ¶ If you enable exact rationals, you
  also get ‘bisection iterators’. These can be useful when one
  implements an algorithm that adaptively bisects intervals.

* Optionally: multiple precision floating point numbers, via the GNU
  Multiple Precision Floating-Point Reliable Library (MPFR). As with
  exact rationals, these are a nonlinear type (for garbage
  collection), and are treated as if they were floating point
  (g0float). ¶ Currently (and probably forever), if you enable
  multiple precision floating point, you also must enable exact
  rationals. However, this should be no problem, because MPFR itself
  uses GMP: if you have the former, you most likely have the
  latter. Furthermore, both are necessary to build GCC.

* Sorting, with algorithms selectable via -DATS flag.

---

References for some obscure integer algorithms, such as for counting
trailing zeros or ones, and calculating population count:

  {{cite web
   | title       = Bit Twiddling Hacks
   | url         = https://graphics.stanford.edu/~seander/bithacks.html
   | date        = 2023-01-14
   | archiveurl  = http://archive.today/GNADt
   | archivedate = 2023-01-14 }}

  {{cite web
   | title       = BitScan - Chessprogramming wiki
   | url         = https://www.chessprogramming.org/index.php?title=BitScan&oldid=22495
   | date        = 2023-02-03
   | archiveurl  = http://archive.today/iPXfa
   | archivedate = 2023-02-03 }}

The algorithms may appear in any of ATS, C, or m4 code.

---

Licensing:

  This program is free software: you can redistribute it and/or
  modify it under the terms of the GNU General Public License, as
  published by the Free Software Foundation, either version 3 of the
  License, or (at your option) any later version.

  This program is distributed in the hope that it will be useful, but
  WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  General Public License for more details.

  You should have received copies of the GNU General Public License
  along with this program. If not, see
  <https://www.gnu.org/licenses/>.

---