matrix.h

大地测量专业计算软件

    std::complex<double> cplx(1.0,2.0);
    Matrix A;
    if( !A.Copy(cplx) )
      return false;
    \endcode
    
    \return true if successful, false otherwise
    */
    bool Copy( const std::complex<double>& cplx );


  public: // Output Operations

    /**
    \brief  Saves a matrix to the specified file path (a 'c' style string)
            using a proprietary compressed format.
    \code
    Matrix A;
    A = "[1,2,3; 4,5,6; 7,8,9]";
    if( !A.Save("data.mtx" ) )
      return false;
    \endcode 

    \return true if successful, false otherwise
    */
    bool Save( const char* path );

    /**
    \brief  Saves a matrix to the specified file path (a std::string)
            using a proprietary compressed format.
            
    \code
    Matrix A;
    std::string str = "data.mtx";
    A = "[1,2,3; 4,5,6; 7,8,9]";
    if( !A.Save(str) )
      return false;
    \endcode 

    \return true if successful, false otherwise
    */
    bool Save( std::string path );
    
    /**
    \brief  Print the matrix to a file with automatically determined column width 
            and the specified precision, uses "%'blank''-'autowidth.precision'g'", to 
            the 'c' style path string provided.
    \code
    A = "[1,2,3; 4,5,6; 7,8,9]";
    if( !A.Print( "data.txt", 14 ) ) // Print the matrix to data.txt
      return false;
    \endcode   

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

    /**
    \brief  Print the matrix to a file with automatically determined column width 
            and the specified precision, uses "%'blank''-'autowidth.precision'g'", to 
            the std:string path provided.
    \code
    A = "[1,2,3; 4,5,6; 7,8,9]";
    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]" );