Community
Modules 15

Data.ByteString.Builder.RealFloat

Floating point formatting for Bytestring.Builder

This module primarily exposes `floatDec` and `doubleDec` which do the equivalent of converting through string7 . show.

It also exposes `formatFloat` and `formatDouble` with a similar API as `GHC.Float.formatRealFloat`.

NB: The float-to-string conversions exposed by this module match `show`'s output (specifically with respect to default rounding and length). In particular, there are boundary cases where the closest and 'shortest' string representations are not used. Mentions of 'shortest' in the docs below are with this caveat.

For example, for fidelity, we match `show` on the output below.

>>> show (1.0e23 :: Float)
"1.0e23"
>>> show (1.0e23 :: Double)
"9.999999999999999e22"
>>> floatDec 1.0e23
"1.0e23"
>>> doubleDec 1.0e23
"9.999999999999999e22"

Simplifying, we can build a shorter, lossless representation by just using "1.0e23" since the floating point values that are 1 ULP away are

>>> showHex (castDoubleToWord64 1.0e23) []
"44b52d02c7e14af6"
>>> castWord64ToDouble 0x44b52d02c7e14af5
9.999999999999997e22
>>> castWord64ToDouble 0x44b52d02c7e14af6
9.999999999999999e22
>>> castWord64ToDouble 0x44b52d02c7e14af7
1.0000000000000001e23

In particular, we could use the exact boundary if it is the shortest representation and the original floating number is even. To experiment with the shorter rounding, refer to `Data.ByteString.Builder.RealFloat.Internal.acceptBounds`. This will give us

>>> floatDec 1.0e23
"1.0e23"
>>> doubleDec 1.0e23
"1.0e23"

For more details, please refer to the Ryu paper.

floatDec :: Float -> Builder

Returns a rendered Float. Matches `show` in displaying in standard or scientific notation

floatDec = 'formatFloat' 'generic'

doubleDec :: Double -> Builder

Returns a rendered Double. Matches `show` in displaying in standard or scientific notation

doubleDec = 'formatDouble' 'generic'

Custom formatting

formatFloat :: FloatFormat -> Float -> Builder

Returns a rendered Float. Returns the 'shortest' representation in scientific notation and takes an optional precision argument in standard notation. Also see `floatDec`.

With standard notation, the precision argument is used to truncate (or extend with 0s) the 'shortest' rendered Float. The 'default precision' does no such modifications and will return as many decimal places as the representation demands.

e.g

>>> formatFloat (standard 1) 1.2345e-2
"0.0"
>>> formatFloat (standard 10) 1.2345e-2
"0.0123450000"
>>> formatFloat standardDefaultPrecision 1.2345e-2
"0.01234"
>>> formatFloat scientific 12.345
"1.2345e1"
>>> formatFloat generic 12.345
"12.345"

formatDouble :: FloatFormat -> Double -> Builder

Returns a rendered Double. Returns the 'shortest' representation in scientific notation and takes an optional precision argument in standard notation. Also see `doubleDec`.

With standard notation, the precision argument is used to truncate (or extend with 0s) the 'shortest' rendered Float. The 'default precision' does no such modifications and will return as many decimal places as the representation demands.

e.g

>>> formatDouble (standard 1) 1.2345e-2
"0.0"
>>> formatDouble (standard 10) 1.2345e-2
"0.0123450000"
>>> formatDouble standardDefaultPrecision 1.2345e-2
"0.01234"
>>> formatDouble scientific 12.345
"1.2345e1"
>>> formatDouble generic 12.345
"12.345"

data FloatFormat

Format type for use with `formatFloat` and `formatDouble`.

standard :: Int -> FloatFormat

Standard notation with `n` decimal places

standardDefaultPrecision :: FloatFormat

Standard notation with the 'default precision' (decimal places matching `show`)

scientific :: FloatFormat

Scientific notation with 'default precision' (decimal places matching `show`)

generic :: FloatFormat

Standard or scientific notation depending on the exponent. Matches `show`

Instances

1
  • instance Show FormatMode
Maintainer
lawrencejwu@gmail.com
Copyright
(c) Lawrence Wu 2021
License
BSD-style
Build record and source files

Community contribution. The service has not verified this documentation. The generator reported 11 diagnostics.

Target: Linux on x86-64. Some inferred types and resolved links are not available.

Generator: aihc-haddock-aa6debbd-web-3

Metadata snapshot: 35f1f56d3dce7f0c7af322ec05f2fba4d1a04564930537462a4ba21b64b756fa

Open the dependency plan · Download the documentation model

Import a package

Enter a package name and an exact version from Hackage. The site contains imported versions only.