matrix.h

大地测量专业计算软件

    \endcode

    In this case '[' donates the start of a matrix and ']' denotes the end. \n
    Row vectors [1 2 3] and [4 5 6] are separated by ';'.  \n
    Commas can delimit row vector data but are not needed. \n
    Complex input: e.g. 
    
    \code
    Matrix A;
    A.SetFromMatrixString( "[1+1i 2+3j 1-2i; 4 5 6]" ); // or
    A.SetFromMatrixString( "[1+1i, 2+3j, 1-2i; 4, 5, 6]" );
    \endcode
    
    (2) Free form delimited matrix. e.g. \n

    \code
    Matrix A; 
    A.SetFromMatrixString( "1 2 3 \\n 4 5 6 \\n" );
    \endcode

    In this case, the newline delimits different rows of the matrix. (\\r\\n also works). \n
    Row vectors can still be delimited by ';' as well. \n
    
    \code
    A.SetFromMatrixString( "1 2 3; 4 5 6; \\n 7 8 9" );
    \endcode 
    
    will set a 3x3 matrix == [1 2 3; 4 5 6; 7 8 9]. \n

    Commas can delimit row vector data but are not needed. \n
    Complex input: e.g. 
    
    \code
    Matrix A;
    A.SetFromMatrixString( "[1+1i 2+3j 1-2i\\n 4 5 6]" );   // or
    A.SetFromMatrixString( "1+1i, 2+3j, 1-2i\\n 4, 5, 6" ); // or
    A.SetFromMatrixString( "1+1i 2+3j 1-2i; 4, 5, 6" );   
    \endcode 

    All result in A = [1+1i 2+3i 1-2i; 4 5 6]; \n
   
    \return true if successful, false otherwise.
    */
    bool SetFromMatrixString(const char* strMatrix);


    /**    
    \brief  Copy the src data in column col to dst matrix, resize dst if possible and necessary.
    
    \code
    Matrix A;
    A = "[1 -1; 2 -2; 3 -3]".
    Matrix B;
    bool result;
    result = A.PrintStdout();   // Print Matrix A.
    result = A.CopyColumn(0,B); // Copy the first column of A into B.
    result = B.PrintStdout();   // Print Matrix B. B = [1;2;3];
    \endcode
    
    \return true if successful, false otherwise.    
    */
    bool CopyColumn( const unsigned src_col, Matrix &dst );

    /**
    \brief  Insert a submatrix (src) into dst, starting at indices dst(row,col).
    
    \code
    Matrix A(4,4); // A 4x4 matrix of zeros.
    Matrix B(2,2); // A 2x2 matrix that we will fill with sevens.
    B.Fill(7.0);
    bool result;
    result = A.PrintStdout();           // Print Matrix A.
    result = A.InsertSubMatrix(B,1,1);  // Put B in the middle of A.
    result = A.PrintStdout();           // Print Matrix A. A = [0 0 0 0; 0 7 7 0; 0 7 7 0; 0 0 0 0].
    \endcode
    
    \return true if successful, false otherwise.    
    */
    bool InsertSubMatrix( const Matrix &src, const unsigned dst_row, const unsigned dst_col );


    /**
    \brief  Extract a submatrix (dst) from this matrix from (inclusive) 
            the rows and columns specified.
    \code 
    Matrix A = "[1 2 3; 4 5 6; 7 8 9]";
    Matrix B;
    bool result = A.ExtractSubMatrix( B, 1, 0, 2, 2 );
    // B == [4 5 6; 7 8 9]
    \endcode

    \return true if successful, false otherwise.
    */
    bool ExtractSubMatrix( 
      Matrix &dst,             //!< The destination matrix to contain the submatrix.
      const unsigned from_row, //!< The zero-based index for the from row.
      const unsigned from_col, //!< The zero-based index for the from column.
      const unsigned to_row,   //!< The zero-based index for the to row.
      const unsigned to_col    //!< The zero-based index for the to column.
      );

    /**
    \brief  Zero the entire matrix.
    
    \code
    Matrix A;
    A = "[1 2 3; 4 5 6; 7 8 9]";
    bool result;
    result = A.PrintStdout();   // Print Matrix A.
    result = A.Zero();          // Set A back to zeros.
    result = A.PrintStdout();   // Print Matrix A. A = [0 0 0; 0 0 0; 0 0 0].
    \endcode
    
    \return true if successful, false otherwise.  
    */
    bool Zero();

    /**
    \brief  Zero all elements in a specified column.
    
    \code
    Matrix A;
    A = "[1 2 3; 4 5 6; 7 8 9]";
    bool result;
    result = A.PrintStdout();   // Print Matrix A.
    result = A.ZeroColumn(1);   // Set the second column of A back to zeros.
    result = A.PrintStdout();   // Print Matrix A. A = [1 0 3; 4 0 6; 7 0 9].
    \endcode
       
    \return true if successful, false otherwise.    
    */
    bool ZeroColumn( const unsigned col );

    /**
    \brief  Zero all elements in a specified row.
    
    \code
    Matrix A;
    A = "[1 2 3; 4 5 6; 7 8 9]";
    bool result;
    result = A.PrintStdout();   // Print Matrix A.
    result = A.ZeroRow(1);      // Set the second row of A back to zeros.
    result = A.PrintStdout();   // Print Matrix A. A = [1 2 3; 0 0 0; 7 8 9].
    \endcode
       
    \return true if successful, false otherwise.    
    */
    bool ZeroRow( const unsigned row );


    /**
    \brief  Efficiently swaps the contents of this matrix with matrix M.
    The contents are exhanged without the need to copy matrix data.

    \code
    Matrix A = "[1 2 3; 4 5 6; 7 8 9]";
    Matrix B = "[1 2; 3 4]";        
    bool result;
    result = A.Swap(B);    
    result = A.PrintStdout();   // Print Matrix A. A = [1 2; 3 4]
    result = B.PrintStdout();   // Print Matrix B. B = [1 2 3; 4 5 6; 7 8 9]
    \endcode

    \return true if successful, false otherwise.    
    */
    bool Swap( Matrix &M );

    /**
    \brief  Fill the matrix with the given value.

    \code
    Matrix A;
    A = "[1 2 3; 4 5 6; 7 8 9]";
    bool result;
    result = A.PrintStdout();   // Print Matrix A.
    result = A.Fill(7);         // Fill the matrix with 7.0.
    result = A.PrintStdout();   // Print Matrix A. A = [7 7 7; 7 7 7; 7 7 7].
    \endcode

    \return true if successful, false otherwise.    
    */
    bool Fill( const double value );

    /**
    \brief  Fill the matrix column with the given value.
    
    \code
    Matrix A;
    A = "[1 2 3; 4 5 6; 7 8 9]";
    bool result;
    result = A.PrintStdout();   // Print Matrix A.
    result = A.FillColumn(1,7); // Fill the second column with 7.0.
    cout << endl;
    result = A.PrintStdout();   // Print Matrix A. A = [1 7 3; 4 7 6; 7 7 9].
    \endcode
    
    \return true if successful, false otherwise.    
    */
    bool FillColumn( const unsigned col, const double value );

    /**
    \brief  Fills the matrix row with the given value.
    
    \code
    Matrix A;
    A = "[1 2 3; 4 5 6; 7 8 9]";
    bool result;
    result = A.PrintStdout();   // Print Matrix A.
    result = A.FillRow(1,7);    // Fill the second row with 7.0.
    cout << endl;
    result = A.PrintStdout();   // Print Matrix A. A = [1 2 3; 7 7 7; 7 8 9].
    \endcode
    
    \return true if successful, false otherwise.    
    */
    bool FillRow( const unsigned row, const double value );

    /**
    \brief  Reverse the order of elements of a column.
    
    \code
    Matrix A;
    A = "[1 2 3; 4 5 6; 7 8 9]";
    bool result;
    result = A.PrintStdout();   // Print Matrix A.
    result = A.FlipColumn(1);   // Flip the second column.
    cout << endl;
    result = A.PrintStdout();   // Print Matrix A. A = [1 8 3; 4 5 6; 7 2 9].
    \endcode
       
    \return true if successful, false otherwise.    
    */
    bool FlipColumn( const unsigned col );

    /**
    \brief  Reverse the order of elements of a row.
    
    \code
    Matrix A;
    A = "[1 2 3; 4 5 6; 7 8 9]";
    bool result;
    result = A.PrintStdout();   // Print Matrix A.
    result = A.FlipRow(1);      // Flip the second row.
    cout << endl;
    result = A.PrintStdout();   // Print Matrix A. A = [1 2 3; 6 5 4; 7 8 9].
    \endcode    
    
    \return true if successful, false otherwise.    
    */
    bool FlipRow( const unsigned row );

    /**
    \brief  Set the matrix to identity using the current dimensions.
    
    \code
    Matrix A;
    A = "[1 2 3; 4 5 6; 7 8 9]";
    bool result;
    result = A.PrintStdout();   // Print Matrix A.
    result = A.Identity();      // Set A to identity.
    cout << endl;
    result = A.PrintStdout();   // Print Matrix A. A = [1 0 0; 0 1 0; 0 0 1].
    \endcode    
    
    \return true if successful, false otherwise.    
    */
    bool Identity();

    /**   
    \brief  Set the matrix to identity using the specified dimension (nxn).
    
    \code
    Matrix A;
    bool result;
    result = A.Identity(3);     // Set A to identity, 3x3.
    cout << endl;
    result = A.PrintStdout();   // Print Matrix A. A = [1 0 0; 0 1 0; 0 0 1].
    \endcode    
    
    \return true if successful, false otherwise.        
    */
    bool Identity(const unsigned dimension);



  public: // Inplace Operations

    /**
    \brief  Transpose the matrix as an inplace operation.
    
    \code
    Matrix A;
    A = "[1 2 3; 4 5 6; 7 8 9]";
    bool result;
    result = A.PrintStdout();         // Print Matrix A.
    result = A.Inplace_Transpose();   // Make A = transpose(A).
    cout << endl;
    result = A.PrintStdout();         // Print Matrix A. A = [1 4 7; 2 5 8; 3 6 9].
    \endcode    
    
    \return true if successful, false otherwise.    
    */
    bool Inplace_Transpose();
    bool Inplace_transpose() { return this->Inplace_Transpose(); }

    /**
    \brief  Round the matrix elements to the specified presision. \n
    e.g. precision = 0    1.8    -> 2     (default)\n
    e.g. precision = 1,   1.45   -> 1.5   \n
    e.g. precision = 2    1.456  -> 1.46  \n
    e.g. precision = 3,   1.4566 -> 1.457 \n
    *
    \code
    Matrix A;
    A = "[1.09 2.08 3.07; 4.06 5.05 6.04; 7.03 8.02 9.01]";
    bool result;
    result = A.PrintStdout();     // Print Matrix A.
    result = A.Inplace_Round(1);  // Make A = round(A) to the 1st decimal place.
    cout << endl;
    result = A.PrintStdout();     // Print Matrix A. A = "[1.1 2.1 3.1; 4.1 5.1 6.0; 7.0 8.0 9.0]";
    \endcode    
    
    \return true if successful, false otherwise.    
    */
    bool Inplace_Round( const unsigned precision = 0 );
    bool Inplace_round( const unsigned precision = 0 ) { return this->Inplace_Round( precision ); }

    /**
    \brief  Round the matrix elements to the nearest integers towards minus infinity.
    
    \code
    Matrix A;
    A = "[1.9 2.8 3.7; -4.6 -5.5 -6.4; 7.3 8.2 9.1]";
    bool result;
    result = A.PrintStdout();     // Print Matrix A.
    result = A.Inplace_Floor();   // Make A = floor(A).
    cout << endl;
    result = A.PrintStdout();     // Print Matrix A. A = "[1 2 3; -5 -6 -7; 7 8 9]";
    \endcode    
       
    \return true if successful, false otherwise.    
    */
    bool Inplace_Floor();
    bool Inplace_floor() { return this->Inplace_Floor(); }

    /**
    \brief  Round the matrix elements to the nearest integers towards infinity.
    
    \code
    Matrix A;
    A = "[1.9 2.8 3.7; -4.6 -5.5 -6.4; 7.3 8.2 9.1]";
    bool result;
    result = A.PrintStdout();     // Print Matrix A.
    result = A.Inplace_Ceil();    // Make A = ceil(A).
    cout << endl;
    result = A.PrintStdout();     // Print Matrix A. A = "[2 3 4; -4 -5 -6; 8 9 10]";
    \endcode    
           
    \return true if successful, false otherwise.    
    */
    bool Inplace_Ceil();
    bool Inplace_ceil() { return this->Inplace_Ceil(); }


    /**
    \brief  Compute the error function (erf) for all values in the matrix inplace. \n
    erf(x) = 2/sqrt(pi) * [integral from 0 to x of]( e^(-t^2) )dt.

    \code
    Matrix A;
    A = "[-1 -0.5 0 0.5 1]";
    bool result;
    result = A.PrintStdout();     // Print Matrix A. A = "[-1 -0.5 0 0.5 1]";
    result = A.Inplace_erf();     // Make A = erf(A).
    cout << endl;
    result = A.PrintStdout();     // Print Matrix A. A = "[-0.842700792949715 -0.520499877813047  0 0.520499877813047 0.842700792949715]";
    \endcode    
           
    \return true if successful, false otherwise.    
    */
    bool Inplace_erf();

    /**
    \brief  Compute the inverse error function (erfinv) for all values in the matrix inplace. \n
    y = erf(x) = 2/sqrt(pi) * [integral from 0 to x of]( e^(-t^2) )dt.
    x = erfinv(y);

    \code
    Matrix A;
    A = "[-0.842700792949715 -0.520499877813047  0 0.520499877813047 0.842700792949715]"; 
    bool result;
    result = A.PrintStdout();     // Print Matrix A. A = "[-0.842700792949715 -0.520499877813047  0 0.520499877813047 0.842700792949715]"; 
    result = A.Inplace_erfinv();  // Make A = erfinv(A).
    cout << endl;
    result = A.PrintStdout();     // Print Matrix A. A = "[-1 -0.5 0 0.5 1]";
    \endcode    
           
    \return true if successful, false otherwise.    
    */
    bool Inplace_erfinv();

    /**
    \brief  Compute the complementary error function (erfc) for all values in the matrix inplace. \n
    erfc(x) = 1 - erf(x) =  2/sqrt(pi) * [integral from x to inf of]( e^(-t^2) )dt.    

    \code
    Matrix A;
    A = "[-1 -0.5 0 0.5 1]";
    bool result;
    result = A.PrintStdout();     // Print Matrix A. A = "[-1 -0.5 0 0.5 1]";
    result = A.Inplace_erfc();    // Make A = erfc(A).
    cout << endl;
    result = A.PrintStdout();     // Print Matrix A. A = "[1.84270079294971  1.52049987781305   1 0.479500122186953 0.157299207050285]";
    \endcode    
           
    \return true if successful, false otherwise.    
    */
    bool Inplace_erfc();

    /**
    \brief  Compute the complementary error function (erfc) for all values in the matrix inplace. \n
    erfc(x) = 1 - erf(x) =  2/sqrt(pi) * [integral from x to inf of]( e^(-t^2) )dt.    

    \code
    Matrix A;
    A = "[1.84270079294971  1.52049987781305   1 0.479500122186953 0.157299207050285]";
    bool result;
    result = A.PrintStdout();     // Print Matrix A. A = "[1.84270079294971  1.52049987781305   1 0.479500122186953 0.157299207050285]";
    result = A.Inplace_erfcinv(); // Make A = erfcinv(A).
    cout << endl;
    result = A.PrintStdout();     // Print Matrix A. A = "[-1 -0.5 0 0.5 1]";
    \endcode    
           
    \return true if successful, false otherwise.    
    */
    bool Inplace_erfcinv();


    /**
    \brief  Rounds the matrix elements of X to the nearest integers towards zero.
    
    \code
    Matrix A;
    A = "[1.9 2.8 3.7; -4.6 -5.5 -6.4; 7.3 8.2 9.1]";
    bool result;
    result = A.PrintStdout();     // Print Matrix A.
    result = A.Inplace_Fix();     // Make A = fix(A).
    cout << endl;
    result = A.PrintStdout();     // Print Matrix A. A = "[1 2 3; -4 -5 -6; 7 8 9]";
    \endcode    
    
    \return true if successful, false otherwise.    
    */
    bool Inplace_Fix();

    /** \brief  Add a scaler double (ie: M += 5).