-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | JSON and CSV encoding for rationals as decimal point numbers.
--   
--   Lossy JSON and CSV encoding and decoding for newtype rationals via
--   scientific with fixed decimal places.
@package detour-via-sci
@version 1.0.0


-- | For encoding and decoding newtype rationals as scientific with a fixed
--   number of decimal places.
module Data.Via.Scientific

-- | A positive number of decimal places.
newtype DecimalPlaces
DecimalPlaces :: Int -> DecimalPlaces

-- | An intermediate type used during encoding to JSON with <tt>aeson</tt>
--   and during encoding to CSV with <tt>cassava</tt>. It's also used
--   during decoding.
--   
--   The original type, a newtype <a>Rational</a>, goes to and fro
--   <b>via</b> <b>sci</b>entific so that the rational value can be encoded
--   as a scientific value with a fixed number of decimal places.
data ViaSci n
[ViaSci] :: (DefaultDecimalPlaces n, Newtype n Rational) => n -> ViaSci n

-- | A default number of decimal places for a type.
class DefaultDecimalPlaces a
defdp :: DefaultDecimalPlaces a => a -> DecimalPlaces

-- | A choice of 8 decimal places for <a>decimal degrees</a> is just a bit
--   more than a mm at the equator and less elsewhere.
--   
--   <ul>
--   <li>1.1132 mm at the equator</li>
--   <li>1.0247 mm at 23° N/S</li>
--   <li>787.1 µm at 45° N/S</li>
--   <li>434.96 µm at 67° N/S</li>
--   </ul>
dpDegree :: DecimalPlaces

-- | Shows a <a>Scientific</a> value with a fixed number of decimal places.
--   
--   <pre>
--   &gt;&gt;&gt; let x = 0.1122334455667788
--   
--   &gt;&gt;&gt; showSci (DecimalPlaces 16) x
--   "0.1122334455667788"
--   
--   &gt;&gt;&gt; showSci (DecimalPlaces 8) x
--   "0.11223345"
--   
--   &gt;&gt;&gt; showSci (DecimalPlaces 4) x
--   "0.1122"
--   
--   &gt;&gt;&gt; showSci (DecimalPlaces 1) x
--   "0.1"
--   
--   &gt;&gt;&gt; showSci (DecimalPlaces 0) x
--   "0"
--   
--   &gt;&gt;&gt; showSci (DecimalPlaces (-1)) x
--   "0"
--   
--   &gt;&gt;&gt; showSci (DecimalPlaces 32) x
--   "0.11223344556677880000000000000000"
--   </pre>
showSci :: DecimalPlaces -> Scientific -> String

-- | From <a>Scientific</a> exactly to <a>Rational</a>.
--   
--   <pre>
--   &gt;&gt;&gt; let x = 0.1122334455667788
--   
--   &gt;&gt;&gt; fromSci x
--   4043636029064415 % 36028797018963968
--   
--   &gt;&gt;&gt; x == fromRational (fromSci x)
--   True
--   </pre>
fromSci :: Scientific -> Rational

-- | To <a>Scientific</a> from <a>Rational</a> as near as possible up to
--   the given number of <a>DecimalPlaces</a> with rounding.
--   
--   <pre>
--   &gt;&gt;&gt; let x = 1122334455667788 % 10000000000000000
--   
--   &gt;&gt;&gt; toSci (DecimalPlaces 8) x
--   0.11223345
--   
--   &gt;&gt;&gt; x == toRational (toSci (DecimalPlaces 8) x)
--   False
--   
--   &gt;&gt;&gt; x == toRational (toSci (DecimalPlaces 16) x)
--   True
--   
--   &gt;&gt;&gt; x == toRational (toSci (DecimalPlaces 32) x)
--   True
--   </pre>
toSci :: DecimalPlaces -> Rational -> Scientific

-- | Taking a number of decimal places from the given <a>DecimalPlaces</a>
--   newtype, derives an instance of <a>DefaultDecimalPlaces</a>.
--   
--   <pre>
--   &gt;&gt;&gt; deriveDecimalPlaces (DecimalPlaces 8) ''Lat
--   ...
--   </pre>
deriveDecimalPlaces :: DecimalPlaces -> Name -> Q [Dec]

-- | Derives an instance of <a>ToJSON</a> wrapping the value with
--   <a>ViaSci</a> before encoding. Similarly the value is decoded as
--   <a>ViaSci</a> and then unwrapped in the derived instance of
--   <a>FromJSON</a>.
--   
--   <pre>
--   &gt;&gt;&gt; deriveJsonViaSci ''Lat
--   ...
--   </pre>
deriveJsonViaSci :: Name -> Q [Dec]

-- | Similar to <a>deriveJsonViaSci</a> but for instances of <a>ToField</a>
--   and <a>FromField</a>.
--   
--   <pre>
--   &gt;&gt;&gt; deriveCsvViaSci ''Lat
--   ...
--   </pre>
deriveCsvViaSci :: Name -> Q [Dec]
instance Language.Haskell.TH.Syntax.Lift Data.Via.Scientific.DecimalPlaces
instance GHC.Show.Show Data.Via.Scientific.DecimalPlaces
instance GHC.Classes.Eq n => GHC.Classes.Eq (Data.Via.Scientific.ViaSci n)
instance GHC.Classes.Ord n => GHC.Classes.Ord (Data.Via.Scientific.ViaSci n)
instance GHC.Show.Show n => GHC.Show.Show (Data.Via.Scientific.ViaSci n)
instance (Data.Via.Scientific.DefaultDecimalPlaces n, Control.Newtype.Newtype n GHC.Real.Rational) => Data.Aeson.Types.ToJSON.ToJSON (Data.Via.Scientific.ViaSci n)
instance (Data.Via.Scientific.DefaultDecimalPlaces n, Control.Newtype.Newtype n GHC.Real.Rational) => Data.Aeson.Types.FromJSON.FromJSON (Data.Via.Scientific.ViaSci n)
instance (Data.Via.Scientific.DefaultDecimalPlaces n, Control.Newtype.Newtype n GHC.Real.Rational) => Data.Csv.Conversion.ToField (Data.Via.Scientific.ViaSci n)
instance (Data.Via.Scientific.DefaultDecimalPlaces n, Control.Newtype.Newtype n GHC.Real.Rational) => Data.Csv.Conversion.FromField (Data.Via.Scientific.ViaSci n)
