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


-- | Rounding rationals to significant digits and decimal places.
--   
--   The round function from the prelude returns an integer. The standard
--   librarys of C and C++ have round functions that return floating point
--   numbers. Rounding in this library takes and returns rationals and can
--   round to a number of significant digits or a number of decimal places.
@package siggy-chardust
@version 1.0.0


-- | Rounding rationals to significant digits and decimal places.
--   
--   The <a>round</a> function from the prelude returns an integer. The
--   standard librarys of C and C++ have round functions that return
--   floating point numbers. Rounding in this library takes and returns
--   <a>Rational</a>s and can round to a number of significant digits or a
--   number of decimal places.
module Data.Ratio.Rounding

-- | Rounds to a non-negative number of <b>d</b>ecimal <b>p</b>laces. After
--   rounding the result would have the given number of decimal places if
--   converted to a floating point number, such as by using
--   <a>fromRational</a>.
--   
--   <pre>
--   &gt;&gt;&gt; dpRound 2 (1234.56789 :: Rational)
--   123457 % 100
--   
--   &gt;&gt;&gt; dpRound 2 (123456789 :: Rational)
--   123456789 % 1
--   </pre>
--   
--   Some examples that may be easier to read using decimal point notation.
--   
--   <pre>
--   &gt;&gt;&gt; dpRound 2 (123456789 :: Rational) == (123456789 :: Rational)
--   True
--   
--   &gt;&gt;&gt; dpRound 2 (1234.56789 :: Rational) == (1234.57 :: Rational)
--   True
--   
--   &gt;&gt;&gt; dpRound 2 (123.456789 :: Rational) == (123.46 :: Rational)
--   True
--   
--   &gt;&gt;&gt; dpRound 2 (12.3456789 :: Rational) == (12.35 :: Rational)
--   True
--   
--   &gt;&gt;&gt; dpRound 2 (1.23456789 :: Rational) == (1.23 :: Rational)
--   True
--   
--   &gt;&gt;&gt; dpRound 2 (0.123456789 :: Rational) == (0.12 :: Rational)
--   True
--   
--   &gt;&gt;&gt; dpRound 2 (0.0123456789 :: Rational) == (0.01 :: Rational)
--   True
--   
--   &gt;&gt;&gt; dpRound 2 (0.0000123456789 :: Rational) == (0.0 :: Rational)
--   True
--   </pre>
--   
--   If the required number of decimal places is less than zero it is taken
--   to be zero.
--   
--   <pre>
--   &gt;&gt;&gt; dpRound 0 (1234.56789 :: Rational)
--   1235 % 1
--   
--   &gt;&gt;&gt; dpRound (-1) (1234.56789 :: Rational)
--   1235 % 1
--   
--   &gt;&gt;&gt; dpRound 0 (123456789 :: Rational)
--   123456789 % 1
--   
--   &gt;&gt;&gt; dpRound (-1) (123456789 :: Rational)
--   123456789 % 1
--   </pre>
--   
--   Rounding to the existing number of decimal places or more makes no
--   difference.
--   
--   <pre>
--   &gt;&gt;&gt; 1234.56789 :: Rational
--   123456789 % 100000
--   
--   &gt;&gt;&gt; dpRound 5 (1234.56789 :: Rational)
--   123456789 % 100000
--   
--   &gt;&gt;&gt; dpRound 6 (1234.56789 :: Rational)
--   123456789 % 100000
--   </pre>
dpRound :: Integer -> Rational -> Rational

-- | Rounds to a non-negative number of <b>s</b>ignificant <b>d</b>igits.
--   
--   <pre>
--   &gt;&gt;&gt; sdRound 1 (123456789 :: Rational)
--   100000000 % 1
--   
--   &gt;&gt;&gt; sdRound 4 (123456789 :: Rational)
--   123500000 % 1
--   
--   &gt;&gt;&gt; sdRound 8 (1234.56789 :: Rational)
--   12345679 % 10000
--   </pre>
--   
--   More examples using decimal point notation.
--   
--   <pre>
--   &gt;&gt;&gt; sdRound 4 (123456789 :: Rational) == (123500000 :: Rational)
--   True
--   
--   &gt;&gt;&gt; sdRound 4 (1234.56789 :: Rational) == (1235 :: Rational)
--   True
--   
--   &gt;&gt;&gt; sdRound 4 (123.456789 :: Rational) == (123.5 :: Rational)
--   True
--   
--   &gt;&gt;&gt; sdRound 4 (12.3456789 :: Rational) == (12.35 :: Rational)
--   True
--   
--   &gt;&gt;&gt; sdRound 4 (1.23456789 :: Rational) == (1.235 :: Rational)
--   True
--   
--   &gt;&gt;&gt; sdRound 4 (0.123456789 :: Rational) == (0.1235 :: Rational)
--   True
--   
--   &gt;&gt;&gt; sdRound 4 (0.0123456789 :: Rational) == (0.01235 :: Rational)
--   True
--   
--   &gt;&gt;&gt; sdRound 4 (0.0000123456789 :: Rational) == (0.00001235 :: Rational)
--   True
--   </pre>
--   
--   Rounding to the existing number of significant digits or more makes no
--   difference.
--   
--   <pre>
--   &gt;&gt;&gt; 1234.56789 :: Rational
--   123456789 % 100000
--   
--   &gt;&gt;&gt; sdRound 9 (1234.56789 :: Rational)
--   123456789 % 100000
--   
--   &gt;&gt;&gt; sdRound 10 (1234.56789 :: Rational)
--   123456789 % 100000
--   </pre>
--   
--   Rounding to zero significant digits is always zero.
--   
--   <pre>
--   &gt;&gt;&gt; sdRound 0 (123456789 :: Rational)
--   0 % 1
--   
--   &gt;&gt;&gt; sdRound 0 (1234.56789 :: Rational)
--   0 % 1
--   
--   &gt;&gt;&gt; sdRound 0 (0.123456789 :: Rational)
--   0 % 1
--   
--   &gt;&gt;&gt; sdRound 0 (0.0000123456789 :: Rational)
--   0 % 1
--   </pre>
sdRound :: Natural -> Rational -> Rational
