cabal-version:      3.0

name:               RoundingFiasco

version:            1.0.0.0

synopsis:
    rounding variants floor, ceil and truncate for floating point operations +-*/√…

description:
    There is an exact definition for `+-*/√` over the real numbers in mathematics.
    However, for performant, flexible, and ergonomic numerical computations one
    ought to restrict oneself to only using a finite subset of rational numbers. The
    most common data types for such use cases are the single and double floating
    point formats.

    Not every floating point value is a real number. There are NaNs, positive and
    negative infinity, and the negative zero. Combining two real floating point
    numbers by an operator yields a mathematical and uncontroversially defined
    result. This exact result might not be representable as a floating point number.
    Therefore, rounding is necessary.

    The most common way of rounding is to select the nearest representable float
    (round-to-nearest-even-on-tie). This rounding variant minimizes the accumulation
    of rounding errors over several floating point operations.

    Other rounding variants (floor, ceil and truncate) are useful for computing
    error bounds of chained floating point instructions. Floor chooses the next
    lower representable value relative to the exact result. Ceil chooses the greater
    neighbor. Truncate chooses the value that is closer to zero.

    This library implements the floating-point-instructions-like operations in pure
    Haskell. The implementation avoids C++ functions like `fegetround`, for example.
    That way they can be used in the WebAssembly backend of GHC since WebAssembly
    supports neither rounding variants nor `fegetround`.

    This module aims to expose the fastest possible pure interface of rounding
    variants. Should there ever be some compiler intrinsics for rounding variants
    then these intrinsics shall be used in a future version.

    Every combination of number type (`Float`, `Double`) and operator
    (`+`,`-`,`*`,`/`,`√`,`id`) is exported separately. The exported functions are
    designed as a basis for interval arithmetic.

    Internally, the module extensively uses the `Rational` data type. First, the
    operation's result is calculated twice. Once done exactly using `Rational`. Then
    a round-to-nearest-even-on-tie result is also calculated. After that, both
    numbers are compared to determine whether the round-to-nearest-even-on-tie
    result happens to be rounded in the correct direction. Should that not be the
    case, the other neighbor is determined and returned.

homepage:
    https://gitlab.com/pauldennis/rounding-fiasco-hackage-package/-/tree/master/rounding-fiasco-hackage-package/processing/RoundingFiasco

license:            MIT

license-file:       LICENSE

author:             Paul Dennis

maintainer:         paul.dennis2@gmx.de

category:           Numerical,Rounding,Interval,Mathematics
build-type:         Simple

extra-doc-files:    CHANGELOG.md

common warnings
    ghc-options: -Wall

library
    import:           warnings

    exposed-modules:  Rounding

    build-depends:    base ^>=4.20.0.0

    hs-source-dirs:   source

    default-language: GHC2021

test-suite RoundingFiasco-test
    import:           warnings

    default-language: GHC2021

    type:             exitcode-stdio-1.0

    hs-source-dirs:   test

    main-is:          Main.hs

    build-depends:
        base ^>=4.20.0.0,
        RoundingFiasco