cwmtx.txt

用C++写的矩阵和矢量运算库

==============================================================================
Documentation of CwMtx Matrix and Vector math template library.  This is not a
tutorial on matrix or quaternion operations just a short description of the
classes contained in the library.

Original author: Harry Kuiper
Email          : [e-mail]

Purpose : This template library provides the matrix and vector operations that
          are used extensively in engineering and science problems.

IMPORTANT: The types used to instantiate the templates in this library need
           not be scalar.  It can be any type that can be treated
           (mathematically) in the same way as a scalar.


==============================================================================
Class hierarchy

                                   +---------+
                                   |CWTMatrix|
                                   +----+----+
                                       -+-
                                        |
                                +-------+-------+
                                |               |
                           +----+----+    +-----+---------+
                           |CWTVector|    |CWTSquareMatrix|
                           +----+----+    +---------------+
                               -+-
                                |
                      +---------+--------+
                      |                  |
                +-----+--------+   +-----+-------+
                |CWTSpaceVector|   |CWTQuaternion|
                +--------------+   +-------------+


==============================================================================
Header file: "cwmtx.h"

Description

   This header file includes all template classes of the library. It also
   contains typedefs that establish compatibility with older (non-template)
   versions of the library.

   namespace CwMtx
   {
     typedef CWTMatrix<> CWMatrix;
     typedef CWTVector<> CWVector;
     typedef CWTSpaceVector<> CWSpaceVector;
     typedef CWTSquareMatrix<> CWSquareMatrix;
     typedef CWTQuaternion<> CWQuaternion;
   }


==============================================================================
template <class T = double> class CWTMatrix

Header file: "matrix.h"

Description

   Template class CWTMatrix provides a mathematical matrix with parameterised
   elements.  It provides the matrix operations that are used extensively in
   engineering and science.  The default element type for this template is
   double.

Public Type Definitions

   enum { N_NOTALLOCATED, N_ALLOCATED, N_MAPPED };

      Enumeration of legal matrix states.  Used by CWTMatrix memory allocation
      routines and initialisation.

      N_NOTALLOCATED = CWTMatrix is empty, no rows or columns are allocated.

      N_ALLOCATED = CWTMatrix has rows and columns.

      N_MAPPED = CWTMatrix is mapped into another matrix.  It has no rows and
                 columns of its own.  It refers to parts of the rows and
                 columns of another matrix.


Public Constructors

   CWTMatrix();

      Default constructor.  Creates a matrix in N_NOTALLOCATED status.  It
      does *NOT* allocate rows and columns.


   CWTMatrix(unsigned crow, unsigned ccol);

      Creates a matrix in N_ALLOCATED status, allocates crow rows and ccol
      columns.


   CWTMatrix(const CWTMatrix<T> &); 

      Copy constructor.  Creates a copy of the argument matrix.  If the
      argument matrix has status N_NOTALLOCATED the copy will be
      N_NOTALLOCATED too.  If the argument matrix has status N_ALLOCATED the
      copy will be N_ALLOCATED too.  If the argument matrix has status
      N_MAPPED the copy will be N_ALLOCATED instead, so it does *NOT* perform
      a shallow copy.  In all cases the values of the elements of the copy
      will equal those of the original.


   CWTMatrix(const CWTMatrix<T> &mat,
             unsigned irowStart,
             unsigned icolStart,
             unsigned irowEnd,
	     unsigned icolEnd);

      Creates a matrix in N_MAPPED status.  I.e. a sub-matrix mapped into the
      argument matrix from element mat[irowStart][icolStart] in the
      "upper-left corner" to mat[irowEnd][icolEnd] in the "lower-right
      corner".


Public Destructors

   ~CWTMatrix();

      Destroys a matrix object.  If the matrix has status N_NOTALLOCATED it
      only destroys itself.  If the matrix has status N_ALLOCATED it destroys
      its rows and columns first.  If the matrix has status N_MAPPED it only
      destroys itself and it does *NOT* deallocate the rows and columns of the
      matrix it was mapped into.


Public Member Functions

   void Dimension(unsigned crow, unsigned ccol);

      Allocates crow rows and ccol columns.  Deallocates existing rows and
      columns first if necessary.  If the matrix has status N_MAPPED it does
      *NOT* deallocate the rows and columns of the matrix it is mapped into it
      only deallocates its own data structures used for the mapping.

   void MapInto(const CWTMatrix<T> &mat,
                unsigned irowStart,
		unsigned icolStart,
		unsigned irowEnd,
		unsigned icolEnd);

      Maps matrix into another matrix from element mat[irowStart][icolStart]
      in the "upper left corner" to mat[irowEnd][icolEnd] in the "lower right
      corner".  Deallocates existing rows and columns first.


   void Deallocate();

      Reverses the effects of calls to constructors, Dimension(..) and
      MapInto(..).  After a call to Deallocate() the matrix always has status
      N_NOTALLOCATED.


   int GetStatus();

      Return the current value of the matrix' status.


   unsigned GetRows();

      Returns the current number of rows in a matrix.


   unsigned GetCols();

      Returns the current number of columns in a matrix.

   void StoreSum(const CWTMatrix<T> &, const CWTMatrix<T> &);

      Stores the sum of two matrices in the destination matrix.  The
      destination matrix must be the right size to accommodate the resulting
      matrix.  This function is provided for situations where using
      operator+() causes too much overhead because it has to construct a new
      result matrix each time it is called.  This can be important when large
      matrices are involved.


   void StoreProduct(const CWTMatrix<T> &, const CWTMatrix<T> &);

      Stores the product of two matrices in the destination matrix.  The
      destination matrix must be the right size to accommodate the resulting
      matrix.  This function is provided for situations where using
      operator*() causes too much overhead because it has to construct a new
      result matrix each time it is called.  This can be important when large
      matrices are involved.


   void StoreTranspose(const CWTMatrix<T> &);

      Stores the transpose of argument matrix in the destination matrix.  This
      function is provided for situations where using transpose(mat) causes too
      much overhead because it has to construct a new result matrix each time
      it is called.  Usually this situation arises when large matrices are
      involved.


   void StoreAtPosition(unsigned irowStart,
                        unsigned icolStart,
			CWTMatrix<T> &mat);

      Stores mat at the position in the destination matrix indicated by "upper
      left corner" irowStart and icolStart.


   void Fill(T elemValue);

      Fills the whole destination matrix with the same value.


   void InterchangeRows(unsigned irow1, unsigned irow2);

      Interchanges rows irow1 and irow2 in the destination matrix.


   void AddRowToRow(unsigned irowSrc, unsigned irowDest, T val = 1);

      Multiplies row irowSrc by value val and adds the result to row irowDest.
      NOTE: The type of argument val may be any type for which a unity element
      exists that can be constructed from 1.


   void MultiplyRow(unsigned irow, T val);

      Multiplies row irow by "scalar" value.


Operators

   T* operator [](unsigned irow);

      Subscript operator.  Returns the row of elements at index irow from the
      matrix it is applied to.  Since a row is defined as an array of
      elements, the standard operator[] for type T can be applied to a row to
      select an element from it.  This operator does *NOT* perform bounds
      checking.


   const T* operator [](unsigned irow) const;

      Returns a row of const elements from a const matrix.  See above for
      details.


   CWTMatrix<T> operator +(const CWTMatrix<T> &) const;

      Matrix addition.


   CWTMatrix<T> operator -(const CWTMatrix<T> &) const;

      Matrix subtraction.


   CWTMatrix<T> operator -() const;

      Returns a matrix of which the sign of of each element is opposed to the
      elements in the matrix the operator is applied to.


   CWTMatrix<T> operator *(T val) const;

      Matrix "scalar" multiplication matrix*val.  NOTE: The type of argument
      val need not be scalar.  It may be any type for which an operator*(..)
      is defined.


   CWTMatrix<T> operator *(const CWTMatrix<T> &) const;

      Matrix multiplication.


   CWTMatrix<T> operator /(T val) const;

      Matrix "scalar" division (multiplies all elements by 1/val).  NOTE:
      The type of argument val need not be scalar.  It may be any type for
      which an operator/(..)  is defined and for which a unity element exists
      that can be constructed from 1.


   CWTMatrix<T> & operator =(const CWTMatrix<T> &);

      Matrix assignment.  If the destination matrix has status N_NOTALLOCATED
      it will be dimensioned automatically to fit the size of the source
      matrix.  Otherwise the matrix should be large enough to hold a copy of
      the source matrix.  (Not inherited.)


   CWTMatrix<T> & operator +=(const CWTMatrix<T> &);

      Compound matrix addition and assignment.


   CWTMatrix<T> & operator -=(const CWTMatrix<T> &);

      Compound matrix subtraction and assignment.


   CWTMatrix<T> & operator *=(T val);

      Compound matrix "scalar" multiplication and assignment.  See NOTE with
      operator*(..).


   CWTMatrix<T> & operator /=(T val);

      Compound matrix "scalar" division and assignment.See NOTE with
      operator/(..).


   int operator ==(const CWTMatrix<T> &) const;

      Matrix comparison.  Returns nonzero if all pairs of corresponding
      elements in both matrices have the same value.  Otherwise returns zero.


   int operator !=(const CWTMatrix<T> &mat) const;

      Matrix comparison.  Returns nonzero if at least one of the pairs of
      corresponding elements in both matrices do not have the same value.
      Otherwise returns zero.


Private Member Functions

   void Initialize();

      Called during construction.  Initialises the matrix' data members to
      values consistent with the N_NOTALLOCATED status.


Private Data Members

   unsigned m_crow;

      Row counter.


   unsigned m_ccol;

      Column counter.


   T **m_rgrow;

      Pointer to an array of pointers to T. Each pointer in the array points
      to the start of a row that contains elements of the matrix (stored on
      free store).


   int m_nMatStatus;

      Matrix status.


Related Global Functions and Operators

   CWTMatrix<T> operator *(T val, const CWTMatrix<T> &)

      Matrix "scalar" mutiplication operator val*matrix.


   CWTMatrix<T> transpose(const CWTMatrix<T> &);

      Returns a matrix that is the transpose of the argument matrix.


   ostream & operator <<(ostream &os, const CWTMatrix<T>& mtx);

      Insert operator that writes the elements of the matrix to a stream in
      row-by-row fashion.


==============================================================================
template <class T = double> CWTSquareMatrix

Header file "smatrix.h"

Description

   Class CWTSquareMatrix provides a mathematical square matrix with
   parameterised elements.  It provides most of the square matrix operations
   that are used extensively in engineering and science.  The default element
   type for this template is double.


Base Classes

   public CWTMatrix<T>


Public Constructors

   CWTSquareMatrix();

      Default constructor.  Constructs a square matrix in N_NOTALLOCATED
      status.


   CWTSquareMatrix(unsigned crowInit);

      Constructs a square matrix in N_ALLOCATED status.  Allocates crowInit
      rows and crowInit columns.


   CWTSquareMatrix(const CWTMatrix<T> &mat);

      Constructs a square matrix from a copy of the argument matrix.  See
      CWTMatrix copy constructor for more details.

      NOTE: The argument matrix should have an equal number of rows and
            columns.  Otherwise runtime errors can occur caused by the
            resulting "square" matrix not being square.


   CWTSquareMatrix(const CWTSquareMatrix<T> &smat);

      Copy constructor.  See CWTMatrix copy constructor for more details.


   CWTSquareMatrix(
      const CWTMatrix<T> &mat,
      unsigned irowStart,
      unsigned icolStart,
      unsigned irowEnd);

      Constructs a square matrix in N_MAPPED status.  The resulting square
      matrix is mapped into the ordinary matrix provided as argument.  Element
      mat[irowStart][icolStart] is taken as "upper-left corner" the mapping
      runs down from there to row irowEnd and an equal number of columns to
      the right.  Deallocates existing rows and columns first or unmaps first
      if needed.


   CWTSquareMatrix(const CWTSquareMatrix<T> &smat,
                   unsigned irowStart,
		   unsigned icolStart,
		   unsigned irowEnd);

      Same as above only maps new square matrix into another square matrix.


Public Destructors

   ~CWTSquareMatrix();

      Destroys a square matrix object.  See ~CWTMatrix() for more details.


Public Member Functions

   void Dimension(unsigned crowInit);

      Dimensions a square matrix at crowInit rows and crowInit columns.  See
      CWTMatrix<T>::Dimension(..) for details.

      NOTE: Since CWTSquareMatrix is derived from CWTMatrix,
            CWTMatrix<T>::Dimension(rows, cols) can be called for a
            CWTSquareMatrix as well, possibly creating a square matrix that is
            not square!  This should be avoided since it can lead to runtime
            errors.


   void MapInto(
      const CWTSquareMatrix<T> &smat,
      unsigned irowStart,
      unsigned icolStart,
      unsigned irowEnd);