Bryan O'Sullivan avatar Bryan O'Sullivan committed f41e032

Add docs.

Comments (0)

Files changed (1)

Data/Double/Conversion.hs

 {-# LANGUAGE ForeignFunctionInterface, MagicHash, Rank2Types,
     UnliftedFFITypes #-}
 
+-- |
+-- Module      : Data.Double.Conversion
+-- Copyright   : (c) 2011 MailRank, Inc.
+--
+-- License     : BSD-style
+-- Maintainer  : bos@mailrank.com
+-- Stability   : experimental
+-- Portability : GHC
+--
+-- Fast, efficient support for converting between double precision
+-- floating point values and text.
+
 module Data.Double.Conversion
     (
       toExponential
 import GHC.Prim (MutableByteArray#)
 import qualified Data.Text.Array as A
 
+-- | Compute a representation in exponential format with the requested
+-- number of digits after the decimal point. The last emitted digit is
+-- rounded.  If -1 digits are requested, then the shortest exponential
+-- representation is computed.
 toExponential :: Int -> Double -> Text
-toExponential ndigits = convert len $ \val mba ->
+toExponential ndigits = convert "toExponential" len $ \val mba ->
                         c_ToExponential val mba (fromIntegral ndigits)
   where len = c_ToExponentialLength
         {-# NOINLINE len #-}
 
+-- | Compute a decimal representation with a fixed number of digits
+-- after the decimal point. The last emitted digit is rounded.
 toFixed :: Int -> Double -> Text
-toFixed ndigits = convert len $ \val mba ->
+toFixed ndigits = convert "toFixed" len $ \val mba ->
                   c_ToFixed val mba (fromIntegral ndigits)
   where len = c_ToFixedLength
         {-# NOINLINE len #-}
 
+-- | Compute the shortest string of digits that correctly represent
+-- the input number.
 toShortest :: Double -> Text
-toShortest = convert len c_ToShortest
+toShortest = convert "toShortest" len c_ToShortest
   where len = c_ToShortestLength
         {-# NOINLINE len #-}
 
+-- | Compute @precision@ leading digits of the given value either in
+-- exponential or decimal format. The last computed digit is rounded.
 toPrecision :: Int -> Double -> Text
-toPrecision ndigits = convert len $ \val mba ->
+toPrecision ndigits = convert "toPrecision" len $ \val mba ->
                       c_ToPrecision val mba (fromIntegral ndigits)
   where len = c_ToPrecisionLength
         {-# NOINLINE len #-}
 
-convert :: CInt -> (forall s. CDouble -> MutableByteArray# s -> IO CInt)
+convert :: String -> CInt
+        -> (forall s. CDouble -> MutableByteArray# s -> IO CInt)
         -> Double -> Text
-convert len act val = runST go
+convert func len act val = runST go
   where
     go = do
       buf <- A.new (fromIntegral len)
       size <- unsafeIOToST $ act (realToFrac val) (A.maBA buf)
-      when (size == -1) $ fail "convert"
+      when (size == -1) .
+        fail $ "Data.Double.Conversion." ++ func ++
+               ": conversion failed (invalid precision requested)"
       frozen <- A.unsafeFreeze buf
       return $! Text frozen 0 (fromIntegral size)
 
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.