bytestring-0.12.1.0: Fast, compact, strict and lazy byte strings with a list interface
Copyright(c) Lawrence Wu 2021
LicenseBSD-style
Maintainerlawrencejwu@gmail.com
Safe HaskellSafe-Inferred
LanguageHaskell2010

Data.ByteString.Builder.RealFloat

Description

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 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 acceptBounds. This will give us

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

For more details, please refer to the Ryu paper.

Since: 0.11.2.0

Synopsis

Documentation

floatDec :: Float -> Builder Source #

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

floatDec = formatFloat generic

doubleDec :: Double -> Builder Source #

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

doubleDec = formatDouble generic

Custom formatting

formatFloat :: FloatFormat -> Float -> Builder Source #

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"

Since: 0.11.2.0

formatDouble :: FloatFormat -> Double -> Builder Source #

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"

Since: 0.11.2.0

data FloatFormat Source #

Format type for use with formatFloat and formatDouble.

Since: 0.11.2.0

standard :: Int -> FloatFormat Source #

Standard notation with n decimal places

Since: 0.11.2.0

standardDefaultPrecision :: FloatFormat Source #

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

Since: 0.11.2.0

scientific :: FloatFormat Source #

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

Since: 0.11.2.0

generic :: FloatFormat Source #

Standard or scientific notation depending on the exponent. Matches show

Since: 0.11.2.0