-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | Formatting of doubles.
--
-- This package provides support for number formatting styles, especially
-- styles involving significant figure calculations.
--
-- Usage
--
--
-- >>> import Data.FormatN
--
-- >>> comma (Just 3) 1234
-- 1,230
--
@package formatn
@version 0.1.0
-- | Text formatting of Doubles.
--
-- In particular, the library provides functionality to calculate and
-- display a fixed number of significant figures for a variety of
-- different number formatting styles.
--
-- Some similar libraries that may be better suited for different use
-- cases include:
--
-- Flexible formatters. These libraries provide more flexibility around
-- formatting options, but do not have a concept of significance:
--
--
--
-- text-format has similar functionality but is not native haskell
-- and I wanted to do some tweaking to defaults. It's probably safer and
-- faster.
--
-- rounded seems to be much more about doing computation taking
-- rounding into account, compared with the much simpler task of pretty
-- printing a number.
--
-- This library could have just provided an ability to compute a
-- significant figure version of a number and then use these other
-- libraries, but the round trip (from Double to SigFig to Double)
-- introduces errors (eg the least significant figure goes from being a
-- '4' to a '3999999' via float maths).
module Data.FormatN
-- | Wrapper for the various formatting options.
--
-- Nothing in the context of these constructors means do not perform and
-- significant figure adjustments to the numbers (or decimal figures with
-- respect to FormatFixed).
data FormatN
FormatFixed :: Maybe Int -> FormatN
FormatDecimal :: Maybe Int -> FormatN
FormatComma :: Maybe Int -> FormatN
FormatExpt :: Maybe Int -> FormatN
FormatPrec :: Maybe Int -> FormatN
FormatDollar :: Maybe Int -> FormatN
FormatPercent :: Maybe Int -> FormatN
FormatNone :: FormatN
-- | The official format
--
--
-- >>> defaultFormatN
-- FormatComma (Just 2)
--
defaultFormatN :: FormatN
-- | run a FormatN
--
--
-- >>> formatN defaultFormatN 1234
-- "1,200"
--
formatN :: FormatN -> Double -> Text
-- | Consistently format a list of numbers via using precision.
--
--
-- >>> formatNs defaultFormatN [0,1,1.01,1.02,1.1,1.2]
-- ["0.00","1.00","1.01","1.02","1.10","1.20"]
--
formatNs :: FormatN -> [Double] -> [Text]
-- | Provide formatted text for a list of numbers so that they are just
-- distinguished.
--
-- For example, precision comma (Just 2) means use as
-- much significant figures as is needed for the numbers to be
-- distinguished on rendering, but with at least 2 significant figures.
--
-- The difference between this and fmap (comma (Just 2))
-- can be seen in these examples:
--
--
-- >>> precision comma (Just 2) [0,1,1.01,1.02,1.1,1.2]
-- ["0.00","1.00","1.01","1.02","1.10","1.20"]
--
--
--
-- >>> fmap (comma (Just 2)) [0,1,1.01,1.02,1.1,1.2]
-- ["0.0","1.0","1.0","1.0","1.1","1.2"]
--
precision :: (Maybe Int -> Double -> Text) -> Maybe Int -> [Double] -> [Text]
-- | Decomposition of a Double into the components that are needed to
-- determine significant figure formatting.
--
-- eliding type changes, the relationship between a Double and a SigFig
-- is:
--
-- <math>
data SigFig
SigFig :: SigFigSign -> Integer -> Int -> SigFig
-- | sign
[sign] :: SigFig -> SigFigSign
-- | significant figures expressed as an Integer
[figures] :: SigFig -> Integer
-- | the power of 10 exponent given figures.
[exponent] :: SigFig -> Int
-- | Sign component
data SigFigSign
SigFigNeg :: SigFigSign
SigFigPos :: SigFigSign
-- | convert from a Double to a SigFig
--
--
-- >>> toSigFig (Just 2) 1234
-- SigFig {sign = SigFigPos, figures = 12, exponent = 2}
--
--
--
-- \x -> let (SigFig s fs e) = toSigFig Nothing x in let x' = ((if (s==SigFigNeg) then (-1.0) else 1.0) * fromIntegral fs * 10.0**fromIntegral e) in (x==0 || abs (x/x'-1) < 1e-6)
--
toSigFig :: Maybe Int -> Double -> SigFig
-- | convert from a SigFig to a Double
--
--
-- >>> fromSigFig (SigFig SigFigPos 12 2)
-- 1200.0
--
--
-- fromSigFig . toSigFig Nothing may not be isomorphic
fromSigFig :: SigFig -> Double
-- | Format to x decimal places with no significant figure rounding.
--
--
-- >>> fixed (Just 2) 100
-- "100.00"
--
--
--
-- >>> fixed (Just 2) 0.001
-- "0.00"
--
fixed :: Maybe Int -> Double -> Text
-- | Format in exponential style, maybe with significant figure rounding.
--
--
-- >>> expt Nothing 1245
-- "1.245e3"
--
--
--
-- >>> expt (Just 3) 1245
-- "1.24e3"
--
--
--
-- >>> expt (Just 3) 0.1245
-- "1.24e-1"
--
expt :: Maybe Int -> Double -> Text
-- | Format in decimal style, and maybe round to n significant figures.
--
--
-- >>> decimal Nothing 1.2345e-2
-- "0.012345"
--
--
--
-- >>> decimal (Just 2) 0.012345
-- "0.012"
--
--
--
-- >>> decimal (Just 2) 12345
-- "12000"
--
decimal :: Maybe Int -> Double -> Text
-- | Format between 0.001 and 1,000,000 using decimal style and exponential
-- style outside this range.
--
--
-- >>> prec (Just 2) 0.00234
-- "0.0023"
--
--
--
-- >>> prec (Just 2) 0.000023
-- "2.3e-5"
--
--
--
-- >>> prec (Just 2) 123
-- "120"
--
--
--
-- >>> prec (Just 2) 123456
-- "120000"
--
--
--
-- >>> prec (Just 2) 1234567
-- "1.2e6"
--
prec :: Maybe Int -> Double -> Text
-- | Format using comma separators for numbers above 1,000 but below 1
-- million, otherwise use prec style.
--
--
-- >>> comma (Just 3) 1234
-- "1,230"
--
comma :: Maybe Int -> Double -> Text
-- | Format as dollars, always using comma notation
--
--
-- >>> dollar (Just 3) 1234
-- "$1,230"
--
--
--
-- >>> dollar (Just 2) 0.01234
-- "$0.012"
--
dollar :: Maybe Int -> Double -> Text
-- | Format as a percentage using decimal style.
--
--
-- >>> percent (Just 2) 0.001234
-- "0.12%"
--
percent :: Maybe Int -> Double -> Text
-- | Format with the shorter of show and formatN.
showOr :: FormatN -> Double -> Text
instance GHC.Generics.Generic Data.FormatN.FormatN
instance GHC.Show.Show Data.FormatN.FormatN
instance GHC.Classes.Eq Data.FormatN.FormatN
instance GHC.Show.Show Data.FormatN.SigFigSign
instance GHC.Classes.Eq Data.FormatN.SigFigSign
instance GHC.Show.Show Data.FormatN.SigFig
instance GHC.Classes.Eq Data.FormatN.SigFig