diff --git a/bed-and-breakfast.cabal b/bed-and-breakfast.cabal --- a/bed-and-breakfast.cabal +++ b/bed-and-breakfast.cabal @@ -1,5 +1,5 @@ Name: bed-and-breakfast -Version: 0.2.2 +Version: 0.2.3 Synopsis: Efficient Matrix operations in 100% Haskell. Description: Efficient Matrix operations in 100% Haskell. . @@ -33,8 +33,10 @@ [@v0.2.1@] Added @cofactors@, @adjugate@, @minor@, and @minorMatrix@. . - [@v0.2.2@] @rank@ works now for any Matrix component - type. + [@v0.2.2@] @rank@ works now for any Matrix component type. + . + [@v0.2.3@] Added 'Read' instance for @Matrix@. + Improved on documentation. License: MIT diff --git a/src/Numeric/Matrix.hs b/src/Numeric/Matrix.hs --- a/src/Numeric/Matrix.hs +++ b/src/Numeric/Matrix.hs @@ -77,7 +77,53 @@ import Prelude hiding (any, all, read, map) import qualified Prelude as P - +-- | Matrices are represented by a type which fits best the component type. +-- For example a @Matrix Double@ is represented by unboxed arrays, +-- @Matrix Integer@ by boxed arrays. +-- +-- Data instances exist for 'Int', 'Float', 'Double', 'Integer', 'Ratio', +-- and 'Complex'. Certain types do have certain disadvantages, like for +-- example you can not compute the inverse matrix of a @Matrix Int@. +-- +-- Every matrix (regardless of the component type) has instances for +-- 'Show', 'Read', 'Num', 'Fractional', 'Eq', 'Typeable', and 'NFData'. +-- This means that you can use arithmetic operations like '+', '*', and +-- '/', as well as functions like 'show', 'read', or 'typeOf'. +-- +-- [@Show (Matrix e)@] +-- Note that a Show instance for the component type @e@ must exist. +-- +-- [@Read (Matrix e)@] +-- You can read a matrix like so: +-- +-- > read "1 0\n0 1\n" :: Matrix Double +-- +-- [@Num (Matrix e)@] +-- '+', '-', '*', 'negate', 'abs', 'signum', and 'fromInteger'. +-- +-- 'signum' will compute the determinant and return the signum +-- of it. +-- +-- 'abs' applies @map abs@ on the matrix (that is, it applies +-- @abs@ on every component in the matrix and returns a new +-- matrix without negative components). +-- +-- @fromInteger@ yields a 1-x-1-matrix. +-- +-- [@Fractional (Matrix e)@] +-- Only available if there exists an instance @Fractional e@ +-- (the component type needs to have a @Fractional@ instance, too). +-- Note that while the 'Num' operations are safe, 'recip' and +-- '/' will fail (with an 'error') if the involved matrix is +-- not invertible or not a square matrix. +-- +-- [@NFData (Matrix e)@] +-- Matrices have instances for NFData so that you can use a +-- matrix in parallel computations using the @Control.Monad.Par@ +-- monad (see the @monad-par@ package for details). +-- +-- [@Typeable (Matrix e)@] +-- Allows you to use matrices as 'Data.Dynamic' values. data family Matrix e data instance Matrix Int @@ -111,11 +157,14 @@ where showRow = unwords . P.map ((' ':) . show) +instance (Read e, MatrixElement e) => Read (Matrix e) where + readsPrec _ = (\x -> [(x, "")]) . fromList . P.map (P.map P.read . words) . lines + instance (MatrixElement e) => Num (Matrix e) where (+) = plus (-) = minus (*) = times - abs = matrix (1,1) . const . abs . det + abs = map abs signum = matrix (1,1) . const . signum . det fromInteger = matrix (1,1) . const . fromInteger @@ -226,30 +275,41 @@ matrix :: (Int, Int) -> ((Int, Int) -> e) -> Matrix e select :: ((Int, Int) -> Bool) -> Matrix e -> [e] + + -- | Returns the component at the given position in the matrix. + -- Note that indices start at one, not at zero. at :: Matrix e -> (Int, Int) -> e + -- | Returns the row at the given index in the matrix. + -- Note that indices start at one, not at zero. row :: Int -> Matrix e -> [e] + + -- | Returns the row at the given index in the matrix. + -- Note that indices start at one, not at zero. col :: Int -> Matrix e -> [e] + -- | The dimensions of a given matrix. dimensions :: Matrix e -> (Int, Int) numRows :: Matrix e -> Int numCols :: Matrix e -> Int - -- Builds a matrix from a list of lists. + -- | Builds a matrix from a list of lists. -- -- > fromList [[1,2,3],[2,1,3],[3,2,1]] :: Matrix Rational fromList :: [[e]] -> Matrix e toList :: Matrix e -> [[e]] - -- An identity square matrix of the given size. + -- | An identity square matrix of the given size. unit :: Int -> Matrix e - -- A square matrix of the given size consisting of all zeros. + -- | A square matrix of the given size consisting of all zeros. zero :: Int -> Matrix e diag :: [e] -> Matrix e + -- | Check whether the matrix is the empty matrix. + -- -- > dimensions empty == (0, 0) empty :: Matrix e @@ -261,16 +321,16 @@ -- adjugate :: Matrix e -> Matrix e -- cofactors :: Matrix e -> Matrix e ; cofactors = undefined - -- Applies Bareiss multistep integer-preserving + -- | Applies Bareiss multistep integer-preserving -- algorithm for finding the determinant of a matrix. -- Returns 0 if the matrix is not a square matrix. det :: Matrix e -> e - -- Flips rows and columns. + -- | Flips rows and columns. -- - -- 1 8 9 1 2 3 - -- 2 1 8 --transpose-> 8 1 2 - -- 3 2 1 9 8 1 + -- > 1 8 9 1 2 3 + -- > 2 1 8 --transpose-> 8 1 2 + -- > 3 2 1 9 8 1 transpose :: Matrix e -> Matrix e rank :: Matrix e -> e trace :: Matrix e -> [e] @@ -280,14 +340,14 @@ adjugate :: MatrixElement e => Matrix e -> Matrix e minorMatrix :: MatrixElement e => Matrix e -> (Int, Int) -> Matrix e - -- Applies a function on every component in the matrix. + -- | Applies a function on every component in the matrix. map :: MatrixElement f => (e -> f) -> Matrix e -> Matrix f - -- Applies a predicate on every component in the matrix + -- | Applies a predicate on every component in the matrix -- and returns True if all components satisfy it. all :: (e -> Bool) -> Matrix e -> Bool - -- Applies a predicate on every component in the matrix + -- | Applies a predicate on every component in the matrix -- and returns True if one or more components satisfy it. any :: (e -> Bool) -> Matrix e -> Bool