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


-- | Exact computation with constructible real numbers
--   
--   The constructible reals are the subset of the real numbers that can be
--   represented exactly using field operations (addition, subtraction,
--   multiplication, division) and positive square roots. They support
--   exact computations, equality comparisons, and ordering.
@package constructible
@version 0.1


-- | The constructible reals, <a>Construct</a>, are the subset of the real
--   numbers that can be represented exactly using field operations
--   (addition, subtraction, multiplication, division) and positive square
--   roots. They support exact computations, equality comparisons, and
--   ordering.
--   
--   <pre>
--   &gt;&gt;&gt; [((1 + sqrt 5)/2)^n - ((1 - sqrt 5)/2)^n :: Construct | n &lt;- [1..10]]
--   [sqrt 5,sqrt 5,2*sqrt 5,3*sqrt 5,5*sqrt 5,8*sqrt 5,13*sqrt 5,21*sqrt 5,34*sqrt 5,55*sqrt 5]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; let f (a, b, t, p) = ((a + b)/2, sqrt (a*b), t - p*((a - b)/2)^2, 2*p)
--   
--   &gt;&gt;&gt; let (a, b, t, p) = f . f . f . f $ (1, 1/sqrt 2, 1/4, 1 :: Construct)
--   
--   &gt;&gt;&gt; floor $ ((a + b)^2/(4*t))*10**40
--   31415926535897932384626433832795028841971
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; let qf (p, q) = ((p + sqrt (p^2 - 4*q))/2, (p - sqrt (p^2 - 4*q))/2 :: Construct)
--   
--   &gt;&gt;&gt; let [(v, w), (x, _), (y, _), (z, _)] = map qf [(-1, -4), (v, -1), (w, -1), (x, y)]
--   
--   &gt;&gt;&gt; z/2
--   -1/16 + 1/16*sqrt 17 + 1/8*sqrt (17/2 - 1/2*sqrt 17) + 1/4*sqrt (17/4 + 3/4*sqrt 17 - (3/4 + 1/4*sqrt 17)*sqrt (17/2 - 1/2*sqrt 17))
--   </pre>
--   
--   Constructible complex numbers may be built from constructible reals
--   using <a>Complex</a> from the complex-generic library.
--   
--   <pre>
--   &gt;&gt;&gt; (z/2 :+ sqrt (1 - (z/2)^2))^17
--   1 :+ 0
--   </pre>
module Data.Real.Constructible

-- | The type of constructible real numbers.
data Construct

-- | Deconstruct a constructible number as either a <a>Rational</a>, or a
--   triple <tt>(a, b, r)</tt> of simpler constructible numbers
--   representing <tt>a + b*sqrt r</tt> (with <tt>b /= 0</tt> and <tt>r
--   &gt; 0</tt>). Recursively calling <a>deconstruct</a> on all triples
--   will yield a finite tree that terminates in <a>Rational</a> leaves.
--   Note that two constructible numbers that compare as equal may
--   deconstruct in different ways.
deconstruct :: Construct -> Either Rational (Construct, Construct, Construct)

-- | Evaluate a floating-point approximation for a constructible number.
--   
--   To improve numerical stability, addition of numbers with different
--   signs is avoided using quadratic conjugation.
fromConstruct :: Floating a => Construct -> a

-- | The type of exceptions thrown by impossible <a>Construct</a>
--   operations.
data ConstructException

-- | <a>toRational</a> was given an irrational constructible number.
ConstructIrrational :: ConstructException

-- | <a>sqrt</a> was given a negative constructible number.
ConstructSqrtNegative :: ConstructException

-- | <a>**</a> was given an exponent that is not a dyadic rational, or a
--   transcendental function was called.
Unconstructible :: String -> ConstructException
instance Floating (Complex Construct)
instance Fractional (Complex Construct)
instance Num (Complex Construct)
instance ComplexPolar (Complex Construct) Construct
instance ComplexRect (Complex Construct) Construct
instance Typeable ConstructException
instance Show FieldShape
instance Eq ConstructException
instance Ord ConstructException
instance Enum Construct
instance RealFrac Construct
instance Real Construct
instance Floating Construct
instance Exception ConstructException
instance Show ConstructException
instance Fractional Construct
instance Num Construct
instance Ord Construct
instance Eq Construct
instance Read Construct
instance Show Construct
instance Show (Field k)