Data.SigFig.Util

A set of (very useful) utility functions, which notably include display and displayInformational.

Documentation

rightmostSignificantPlace :: Integer -> BigDecimal -> Integer

Get the rightmost significant decimal place given a number of significant figures sf and a BigDecimal bd. It is as if one were calculating the value for a Measured sf bd.

A negative return value is allowed and meaningful.

>>> rightmostSignificantPlace 2 (BigDecimal 42 1)
-1

forceDP :: Integer -> BigDecimal -> Term

Force a given BigDecimal to have a certain number of significant decimal places. A positive integer means to the left of decimal place, negative means to the right.

Examples

>>> forceDP (-2) (fromRational 123.456)
Measured {numSigFigs = 5, value = 123.46}

>>> forceDP 2 (fromRational 123.456)
Measured {numSigFigs = 1, value = 100}

forceSF :: Integer -> BigDecimal -> Term

Force a given BigDecimal to have a certain number of significant figures. A positive integer means to the left of decimal place, negative means to the right.

roundToPlace :: BigDecimal -> Integer -> BigDecimal

Round a BigDecimal to a specified decimal place. A positive integer means to the left of decimal place, negative means to the right.

>>> roundToPlace (BigDecimal 421 1) (0)
42

display :: Term -> Text

Given a term, display it in the most convenient way possible. This means, if the normal representation of the number accurately represents how many significant figures it has, then display it normally. Adds trailing zeroes if necessary to floats and opts for scientific notation if necessary.

Examples

>>> display $ measured 3 200
"200."

>>> display $ measured 3 4
"4.00"

>>> display $ measured 2 400
"4.0 x 10^2"

>>> display $ measured 2 430
"430"

>>> display $ measured 1 1
"1"

>>> display $ constant (3 % 8)
"0.375"

>>> display $ constant (4 % 9)
"4/9"

>>> display $ measured 2 4.3
"4.3"

displayFull :: Term -> Text

Used in the CLI. Not super pretty but gets the job done in terms of displaying enough information.

Examples

>>> displayFull (constant 3.45)
"3.45 (const)"

>>> displayFull (measured 3 8500)
"8.50 x 10^3 (3 s.f.)"

displayInformational :: Term -> (Text, Text)

Given a term, return a tuple where the first element is the output of display and the second is an annotation of the type of value. Used in the API.

Examples

>>> displayInformational $ constant 3
("3","constant value")

>>> displayInformational $ measured 2 3.4
("3.4","2 significant figures")

>>> displayInformational $ measured 3 3400
("3.40 x 10^3","3 significant figures")

isTerminating :: Integer -> Bool

Given a denominator, tell if the decimal expansion of the fraction terminates. Useful for telling whether a constant value is a terminating or non-terminating value. But one should probably use displayInformational to extract such information.