X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=Data%2FComplex.hs;h=3b37f6c91f0b8dea033afffd3ce03c7d38e5ad3f;hb=8c4b9f779fe4f3ad108124654e2230e335819e6e;hp=f2cef50dc264244ea8632b30e3239d4d0f932776;hpb=acd78d6dbda0108ffa899cb585114a21c5ed7499;p=ghc-base.git

diff --git a/Data/Complex.hs b/Data/Complex.hs
index f2cef50..3b37f6c 100644
--- a/Data/Complex.hs
+++ b/Data/Complex.hs
@@ -13,17 +13,21 @@
 -----------------------------------------------------------------------------
 
 module Data.Complex
-	( Complex((:+))
-	
+	(
+	-- * Rectangular form
+	  Complex((:+))
+
 	, realPart	-- :: (RealFloat a) => Complex a -> a
 	, imagPart      -- :: (RealFloat a) => Complex a -> a
-	, conjugate     -- :: (RealFloat a) => Complex a -> Complex a
+	-- * Polar form
 	, mkPolar       -- :: (RealFloat a) => a -> a -> Complex a
 	, cis           -- :: (RealFloat a) => a -> Complex a
 	, polar         -- :: (RealFloat a) => Complex a -> (a,a)
 	, magnitude     -- :: (RealFloat a) => Complex a -> a
 	, phase         -- :: (RealFloat a) => Complex a -> a
-	
+	-- * Conjugate
+	, conjugate     -- :: (RealFloat a) => Complex a -> Complex a
+
 	-- Complex instances:
 	--
 	--  (RealFloat a) => Eq         (Complex a)
@@ -39,8 +43,9 @@ module Data.Complex
 
 import Prelude
 
-#ifndef __NHC__
-import Data.Dynamic
+import Data.Typeable
+#ifdef __GLASGOW_HASKELL__
+import Data.Generics.Basics( Data )
 #endif
 
 #ifdef __HUGS__
@@ -52,32 +57,56 @@ infix  6  :+
 -- -----------------------------------------------------------------------------
 -- The Complex type
 
-data  (RealFloat a)     => Complex a = !a :+ !a  deriving (Eq, Read, Show)
-
+-- | Complex numbers are an algebraic type.
+--
+-- For a complex number @z@, @'abs' z@ is a number with the magnitude of @z@,
+-- but oriented in the positive real direction, whereas @'signum' z@
+-- has the phase of @z@, but unit magnitude.
+data (RealFloat a) => Complex a
+  = !a :+ !a	-- ^ forms a complex number from its real and imaginary
+		-- rectangular components.
+# if __GLASGOW_HASKELL__
+	deriving (Eq, Show, Read, Data)
+# else
+	deriving (Eq, Show, Read)
+# endif
 
 -- -----------------------------------------------------------------------------
 -- Functions over Complex
 
-realPart, imagPart :: (RealFloat a) => Complex a -> a
+-- | Extracts the real part of a complex number.
+realPart :: (RealFloat a) => Complex a -> a
 realPart (x :+ _) =  x
+
+-- | Extracts the imaginary part of a complex number.
+imagPart :: (RealFloat a) => Complex a -> a
 imagPart (_ :+ y) =  y
 
+-- | The conjugate of a complex number.
 {-# SPECIALISE conjugate :: Complex Double -> Complex Double #-}
 conjugate	 :: (RealFloat a) => Complex a -> Complex a
 conjugate (x:+y) =  x :+ (-y)
 
+-- | Form a complex number from polar components of magnitude and phase.
 {-# SPECIALISE mkPolar :: Double -> Double -> Complex Double #-}
 mkPolar		 :: (RealFloat a) => a -> a -> Complex a
 mkPolar r theta	 =  r * cos theta :+ r * sin theta
 
+-- | @'cis' t@ is a complex value with magnitude @1@
+-- and phase @t@ (modulo @2*'pi'@).
 {-# SPECIALISE cis :: Double -> Complex Double #-}
 cis		 :: (RealFloat a) => a -> Complex a
 cis theta	 =  cos theta :+ sin theta
 
+-- | The function 'polar' takes a complex number and
+-- returns a (magnitude, phase) pair in canonical form:
+-- the magnitude is nonnegative, and the phase in the range @(-'pi', 'pi']@;
+-- if the magnitude is zero, then so is the phase.
 {-# SPECIALISE polar :: Complex Double -> (Double,Double) #-}
 polar		 :: (RealFloat a) => Complex a -> (a,a)
 polar z		 =  (magnitude z, phase z)
 
+-- | The nonnegative magnitude of a complex number.
 {-# SPECIALISE magnitude :: Complex Double -> Double #-}
 magnitude :: (RealFloat a) => Complex a -> a
 magnitude (x:+y) =  scaleFloat k
@@ -85,6 +114,8 @@ magnitude (x:+y) =  scaleFloat k
 		    where k  = max (exponent x) (exponent y)
 		          mk = - k
 
+-- | The phase of a complex number, in the range @(-'pi', 'pi']@.
+-- If the magnitude is zero, then so is the phase.
 {-# SPECIALISE phase :: Complex Double -> Double #-}
 phase :: (RealFloat a) => Complex a -> a
 phase (0 :+ 0)   = 0		-- SLPJ July 97 from John Peterson
@@ -94,10 +125,8 @@ phase (x:+y)	 = atan2 y x
 -- -----------------------------------------------------------------------------
 -- Instances of Complex
 
-#ifndef __NHC__
 #include "Typeable.h"
 INSTANCE_TYPEABLE1(Complex,complexTc,"Complex")
-#endif
 
 instance  (RealFloat a) => Num (Complex a)  where
     {-# SPECIALISE instance Num (Complex Float) #-}
@@ -107,7 +136,7 @@ instance  (RealFloat a) => Num (Complex a)  where
     (x:+y) * (x':+y')	=  (x*x'-y*y') :+ (x*y'+y*x')
     negate (x:+y)	=  negate x :+ negate y
     abs z		=  magnitude z :+ 0
-    signum 0		=  0
+    signum (0:+0)	=  0
     signum z@(x:+y)	=  x/r :+ y/r  where r = magnitude z
     fromInteger n	=  fromInteger n :+ 0
 #ifdef __HUGS__
@@ -136,7 +165,7 @@ instance  (RealFloat a) => Floating (Complex a)	where
                       where expx = exp x
     log z          =  log (magnitude z) :+ phase z
 
-    sqrt 0         =  0
+    sqrt (0:+0)    =  0
     sqrt z@(x:+y)  =  u :+ (if y < 0 then -v else v)
                       where (u,v) = if x < 0 then (v',u') else (u',v')
                             v'    = abs y / (u'*2)