Permalink
Browse files

Add docs.

  • Loading branch information...
1 parent b15f157 commit 5742e7c193e9dc57d575642e41b3f205e805918b @bos committed Jun 26, 2011
Showing with 32 additions and 7 deletions.
  1. +32 −7 Data/Double/Conversion.hs
View
@@ -1,6 +1,18 @@
{-# 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
@@ -16,37 +28,50 @@ import Foreign.C.Types (CDouble, CInt)
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)

0 comments on commit 5742e7c

Please sign in to comment.