matrix.h

矩阵类

    std::string str = "data.txt";
    if( !A.Print( str, 14 ) ) // Print the matrix to data.txt
      return false;
    \endcode   

    \return true if successful, false otherwise
    */
    bool Print( std::string path, const unsigned precision, bool append = false );

    /**
    \brief  Print the matrix to the standard output (stdout) with automatically 
            determined column width and the specified precision, 
            uses "%'blank''-'autowidth.precision'g'".
    \code
    Matrix A;
    A = "[1.123 0 2.123 -1; 3.123 0 4.123 -1]";  // Set A using string notation.
    bool result = A.PrintStdout(6); // Print to stdout with automatic width determination.
    // results in:
    // 0123456789012345678901234567890
    //  1.123  0  2.123 -1
    //  3.123  0  4.123 -1
    \endcode
        
    \return true if successful, false otherwise
    */
    bool PrintStdout( const unsigned precision = 6 );

    /**
    \brief  Print the matrix to a buffer of maxlength with automatically determined column width 
    and the specified precision, uses "%'blank''-'autowidth.precision'g'"

    \code
    Matrix A;
    A = "[1.123 0 2.123 -1; 3.123 0 4.123 -1]";  // Set A using string notation.
    char buffer[256]; 
    bool result = A.PrintToBuffer( buffer, 256, 6); // Print to a buffer with automatic width determination.
    cout << buffer << endl;
    // results in:
    // 0123456789012345678901234567890
    //  1.123  0  2.123 -1
    //  3.123  0  4.123 -1
    \endcode
     
    \return true if successful, false otherwise
    */
    bool PrintToBuffer( char* buffer, const unsigned maxlength, const unsigned precision );


    /**
    \brief  Print the matrix to a file with specifed width and precision
            PrintAutoWidth is recommended over this function, "%'blank''-'width.precision'g'"
            to file specified with the 'c' style path string provided.
    \code
    Matrix A;
    A = "[1.123 0 2.123 -1; 3.123 0 4.123 -1]";  // Set A using string notation.
    if( !A.PrintFixedWidth( "data.txt", 6, 3 ) )
      return false;
    // results in: data.txt with
    // 0123456789012345678901234567890
    //  1.123     0 2.123    -1
    //  3.123     0 4.123    -1
    \endcode

    \return true if successful, false otherwise
    */
    bool PrintFixedWidth( const char* path, const unsigned width, const unsigned precision, bool append = false );


    /**
    \brief  Print the matrix to a file with specifed width and precision
            PrintAutoWidth is recommended over this function, "%'blank''-'width.precision'g'"
            to file specified with the std::string path string provided.
    \code
    Matrix A;
    A = "[1.123 0 2.123 -1; 3.123 0 4.123 -1]";  // Set A using string notation.
    std::string str = "data.txt";
    if( !A.PrintFixedWidth( str, 6, 3 ) )
      return false;
    // results in: data.txt with
    // 0123456789012345678901234567890
    //  1.123     0 2.123    -1
    //  3.123     0 4.123    -1
    \endcode

    \return true if successful, false otherwise
    */   
    bool PrintFixedWidth( std::string path, const unsigned width, const unsigned precision, bool append = false );

    /**
    \brief  Print the matrix to a buffer of maxlength with specifed width and precision
            PrintAutoWidth is recommended over this function, "%'blank''-'width.precision'g'"
    \code
    Matrix A;
    A = "[1.123 2.123 -1; 3.123 4.123 -1]";  // Set A using string notation.
    char buffer[256]; 
    bool result = A.PrintFixedWidthToBuffer( buffer, 256, 10, 6 ); // Print to a buffer with fixed width.
    cout << buffer << endl;
    // results in:
    // 0123456789012345678901234567890    
    //  1.123     2.123    -1
    //  3.123     4.123    -1
    \endcode
      
    \return true if successful, false otherwise
    */
    bool PrintFixedWidthToBuffer( char* buffer, const unsigned maxlength, const unsigned width, const unsigned precision );

    /**
    \brief  Print the matrix to a file path specified by the 'c' style string 
            with specifed precision and delimiter.
    \code
    Matrix A;
    A = "[1.123 2.123 -1; 3.123 4.123 -1]";  // Set A using string notation.
    if( !A.PrintDelimited( "data.csv", 5, ',' ) )
      return false;
    // results in: data.csv with
    // 0123456789012345678901234567890    
    // 1.123,2.123,-1
    // 3.123,4.123,-1
    \endcode

    \return true if successful, false otherwise
    */
    bool PrintDelimited( const char *path, const unsigned precision, const char delimiter, bool append = false );

    /**
    \brief  Print the matrix to a file path specified by the std::string 
            with specifed precision and delimiter.
    \code
    Matrix A;
    A = "[1.123 2.123 -1; 3.123 4.123 -1]";  // Set A using string notation.
    std::string str = "data.csv";
    if( !A.PrintDelimited( str, 5, ',' ) )
      return false;
    // results in: data.csv with
    // 0123456789012345678901234567890    
    // 1.123,2.123,-1
    // 3.123,4.123,-1
    \endcode

    \return true if successful, false otherwise
    */
    bool PrintDelimited( std::string path, const unsigned precision, const char delimiter, bool append = false );
    
    /**
    \brief  Print the matrix to a 'c' style string buffer of maxlength with specifed precision and delimiter.
    
    \code
    Matrix A;
    A = "[1.123 2.123; 3.123 4.123]";  // Set A using string notation.
    char buffer[256]; 
    if( !A.PrintDelimitedToBuffer( buffer, 256, 6, ',' ) ) // Print to a buffer using comma delimiters.
      return false;
    cout << buffer << endl;
    // results in:
    // 1.123,2.123
    // 3.123,4.123
    \endcode
      
    \return true if successful, false otherwise
    */
    bool PrintDelimitedToBuffer( char *buffer, const unsigned maxlength, const unsigned precision, const char delimiter );

    /**
    \brief  Print a row to a 'c' style string buffer.
    
    \code
    Matrix A;
    A = "[1.123 2.123; 3.123 4.123]";  // Set A using string notation.
    char buffer[256]; 
    if( !A.PrintRowToString( 1, buffer, 256, 4, 6 ) ) // Print the second row to the char buffer.
      return false;
    cout << buffer << endl;
    // results in:
    // 3.123   4.123
    \endcode
    
    \return true if successful, false otherwise
    */
    bool PrintRowToString( const unsigned row, char *buffer, const unsigned maxlength, const int width, const int precision );


  public: // Change the dimensions of the matrix

    /**  
    \brief  Remove a single column from the matrix.

    \code
    Matrix A;
    A = "[1.123 0 2.123; 3.123 0 4.123]";  // Set A using string notation.
    if( !A.RemoveColumn(1) ) // Remove the column with the zeros
      return false;
    // results in 
    // A
    // 1.123 2.123
    // 3.123 4.123
    \endcode
        
    \return true if successful, false otherwise.  
    */
    bool RemoveColumn( const unsigned col );

    /**
    \brief  Remove all the columns 'after' the column index given.

    \code
    Matrix A;
    A = "[1.123 0 2.123; 3.123 0 4.123]";  // Set A using string notation.
    if( !A.RemoveColumnsAfterIndex(0) ) // Remove the 2nd and 3rd columns, i.e. after the 0th column.
      return false;
    // results in 
    // A
    // 1.123
    // 3.123
    \endcode
    
    \return true if successful, false otherwise.  
    */
    bool RemoveColumnsAfterIndex( const unsigned col );

    /** 
    \brief  Remove the rows and columns specified by the indices in the rows[] and cols[] arrays.
    
    \code
    Matrix A(4,4);
    unsigned rows[2];
    unsigned cols[2];
    rows[0] = 0; // remove row 0
    rows[1] = 2; // remove row 2
    cols[0] = 0; // remove column 0
    cols[1] = 2; // romve column 2
    A.RemoveRowsAndColumns( 2, (unsigned int *)rows, 2, (unsigned int *)cols );
    // A is now a 2x2 matrix
    \endcode
    
    \return true if successful, false otherwise.  
    */
    bool RemoveRowsAndColumns( const unsigned nrows, const unsigned rows[], const unsigned ncols, const unsigned cols[] );

    /**
    \brief  Insert a column matrix into the matrix.
    
    \code
    Matrix A;
    Matrix B(2,2);
    A = "[1.123 2.123; 3.123 4.123]";  // Set A using string notation.
    if( !A.InsertColumn( B, 1, 1 ) ) // Insert second column of B into the second column a A.
      return false;
    // results in:
    // A (2x3)
    // 1.123  0   2.123
    // 3.123  0   4.123
    \endcode
    
    \return true if successful, false otherwise.  
    */
    bool InsertColumn( const Matrix &src, const unsigned dst_col, const unsigned src_col );

    /** 
    \brief  Add a column to the end of the matrix.

    \code
    Matrix A;
    atrix B(2,2);
    A = "[1.123 2.123; 3.123 4.123]";  // Set A using string notation.
    if( !A.AddColumn( B, 1 ) ) // Add second column of B to A.
      return false;
    // results in:
    // A (2x3)
    // 1.123  2.123 0
    // 3.123  4.123 0
    \endcode
    
    \return true if successful, false otherwise.  
    */
    bool AddColumn( const Matrix &src, const unsigned src_col );

    /**
    \brief  Combine two matrices with the same nrows, A becomes A|B.

    \code
    Matrix A;
    atrix B(2,2);
    A = "[1.123 2.123; 3.123 4.123]";  // Set A using string notation.
    if( !A.Concatonate( B ) ) // make A = A | B
      return false;
    // results in:
    // A (2x4)
    // 1.123  2.123 0 0
    // 3.123  4.123 0 0
    \endcode

    \return true if successful, false otherwise.  
    */
    bool Concatonate( const Matrix &src );

    /**
    \brief  Redimension the matrix, original data is saved in place, new 
            data is set to zero. The default value for ncols allows 
            redimensioning as a vector.
    \code
    Matrix A(4,4);       // A is 4x4
    A[0][0] = 1;
    A[1][1] = -1;
    if( !A.Redim(2,2) )  // A is 2x2 but data values are retained.
      return false;
    // results in:
    // A (2x2)
    // 1  0
    // 0 -1

    Matrix B(10);     // B is a vector with length 10.
    B[0] = -1;
    B[1] = 1;
    if( !B.Redim(2) ) // B is a vector with length 2 but data values are retained
      return false;
    // results in:
    // B 
    // -1
    // 1
    \endcode
    
    \return true if successful, false otherwise.  
    */
    bool Redim( const unsigned nrows, const unsigned ncols=1 );

    /**
    \brief  Resize the matrix, original data is lost, new data is set to zero.
            The default value for ncols allows resizing as a vector.

    \code
    Matrix A(4,4);       // A is 4x4
    A[0][0] = 1;
    A[1][1] = -1;
    if( !A.Resize(2,2) )  // A is 2x2 and zero.
      return false;
    // results in:
    // A (2x2)
    // 0 0
    // 0 0

    Matrix B(10);     // B is a vector with length 10.
    B[0] = -1;
    B[1] = 1;
    if( !B.Resize(2) ) // B is a vector with length 2 and is zero.
      return false;
    // results in:
    // B 
    // 0
    // 0
    \endcode
            
    \return true if successful, false otherwise.  
    */
    bool Resize( const unsigned nrows, const unsigned ncols=1 );


  public: // Setting matrix values

    /**
    \brief  Set the matrix from the static 'c' style matrix indexed by mat[i*ncols + j].

    \code
    Matrix A;
    double data[4] = {1.0,2.0,3.0,4.0};
    if( !A.SetFromStaticMatrix( data, 1, 4 ) )
      return false;
    \\ results in 
    \\ A
    \\ 1.0 2.0 3.0 4.0
    if( !A.SetFromStaticMatrix( data, 2, 2 ) )
      return false;    
    \\ results in 
    \\ A
    \\ 1.0 2.0 
    \\ 3.0 4.0    
    \endcode
    
    \return true if successful, false otherwise.    
    */
    bool SetFromStaticMatrix( const double mat[], const unsigned nrows, const unsigned ncols );

    /**
    \brief  Setting the matrix values from a string matrix.
    
    There are two general possible interpretations of the string input. \n
    
    (1) Square bracket delimited matrix. e.g. \n
    
    \code
    Matrix A;
    A.SetFromMatrixString( "[1 2 3; 4 5 6]" ); // or 
    A.SetFromMatrixString( "[1, 2, 3; 4, 5, 6]" );
    \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.